0
# Jetty Integration
1

2
Configuration utilities and integration patterns for enabling JSTL functionality within Eclipse Jetty web applications, including WebAppContext setup and container include patterns.
3

4
## Integration Components
5

6
### JspConfig Utility Class
7

8
Centralized configuration utility for setting up JSP and JSTL processing in Jetty WebAppContext instances.
9

10
```java { .api }
11
package org.eclipse.jetty.jstl;
12

13
public class JspConfig {
14
    /**
15
     * Initialize WebAppContext for JSP and JSTL processing.
16
     * 
17
     * Configures servlet context temporary directory, container include JAR patterns,
18
     * and resource base paths for proper JSTL library loading and JSP compilation.
19
     *
20
     * @param context WebAppContext to configure for JSTL support
21
     * @param baseUri Base URI for the web application resources
22
     * @param scratchDir Temporary directory for JSP compilation artifacts
23
     */
24
    public static void init(WebAppContext context, URI baseUri, File scratchDir);
25
}
26
```
27

28
**Usage Example:**
29

30
```java
31
import org.eclipse.jetty.jstl.JspConfig;
32
import org.eclipse.jetty.webapp.WebAppContext;
33
import java.io.File;
34
import java.net.URI;
35

36
// Create WebAppContext
37
WebAppContext context = new WebAppContext();
38
context.setContextPath("/myapp");
39

40
// Setup directories
41
File webAppDir = new File("src/main/webapp");
42
File scratchDir = new File("target/jsp-scratch");
43

44
// Initialize JSTL configuration
45
JspConfig.init(context, webAppDir.toURI(), scratchDir);
46

47
// Additional context configuration
48
context.addConfiguration(new AnnotationConfiguration());
49
```
50

51
### Container Include Patterns
52

53
The module configures specific JAR patterns to ensure JSTL libraries are properly included in the web application classpath.
54

55
```java { .api }
56
// Configured JAR patterns for container inclusion:
57
String CONTAINER_INCLUDE_JAR_PATTERN = 
58
    ".*/jetty-jakarta-servlet-api-[^/]*\\.jar$|" +
59
    ".*jakarta.servlet.jsp.jstl-[^/]*\\.jar|" +
60
    ".*taglibs-standard.*\\.jar";
61
```
62

63
This pattern ensures the following JARs are included:
64
- Jakarta Servlet API JAR files
65
- JSTL API JAR files (`jakarta.servlet.jsp.jstl`)
66
- Apache JSTL implementation JARs (`taglibs-standard`)
67

68
### Module Configuration
69

70
Jetty module descriptor that enables JSTL support system-wide.
71

72
```ini { .api }
73
# Module: apache-jstl.mod
74
[description]
75
Enables the apache version of JSTL for all webapps.
76

77
[lib]
78
lib/apache-jstl/*.jar
79
```
80

81
**Module Activation:**
82

83
```bash
84
# Command line activation
85
java -jar jetty-start.jar --module=apache-jstl
86

87
# Or via start.ini
88
--module=apache-jstl
89
```
90

91
### WebAppContext Configuration Details
92

93
The `JspConfig.init()` method performs the following configuration steps:
94

95
1. **Temporary Directory Setup:**
96
   ```java
97
   context.setAttribute("jakarta.servlet.context.tempdir", scratchDir);
98
   ```
99

100
2. **Container Include Pattern Configuration:**
101
   ```java
102
   context.setAttribute("org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern",
103
       ".*/jetty-jakarta-servlet-api-[^/]*\\.jar$|.*jakarta.servlet.jsp.jstl-[^/]*\\.jar|.*taglibs-standard.*\\.jar");
104
   ```
105

106
3. **Resource Base Configuration:**
107
   ```java
108
   context.setWar(baseUri.toASCIIString());
109
   context.setResourceBase(baseUri.toASCIIString());
110
   ```
111

112
## Integration Patterns
113

114
### Test Environment Setup
115

116
Complete example of setting up a test environment with JSTL support:
117

118
```java
119
import org.eclipse.jetty.annotations.AnnotationConfiguration;
120
import org.eclipse.jetty.server.Server;
121
import org.eclipse.jetty.server.ServerConnector;
122
import org.eclipse.jetty.toolchain.test.FS;
123
import org.eclipse.jetty.webapp.WebAppContext;
124
import org.eclipse.jetty.jstl.JspConfig;
125

126
public class JstlTestSetup {
127
    public static Server createTestServer() throws Exception {
128
        // Create server
129
        Server server = new Server();
130
        ServerConnector connector = new ServerConnector(server);
131
        connector.setPort(0); // Use random available port
132
        server.addConnector(connector);
133

134
        // Setup web application directory
135
        File testWebAppDir = new File("src/test/webapp");
136
        File scratchDir = new File("target/test-scratch");
137
        FS.ensureEmpty(scratchDir);
138

139
        // Configure WebAppContext
140
        WebAppContext context = new WebAppContext();
141
        context.setContextPath("/");
142
        
143
        // Initialize JSTL configuration
144
        JspConfig.init(context, testWebAppDir.toURI(), scratchDir);
145
        
146
        // Add annotation processing
147
        context.addConfiguration(new AnnotationConfiguration());
148
        
149
        server.setHandler(context);
150
        return server;
151
    }
152
}
153
```
154

155
### Production Deployment
156

157
Maven dependency configuration for production deployment:
158

159
```xml
160
<dependencies>
161
    <!-- Apache JSTL Module -->
162
    <dependency>
163
        <groupId>org.eclipse.jetty</groupId>
164
        <artifactId>apache-jstl</artifactId>
165
        <version>11.0.0</version>
166
    </dependency>
167
    
168
    <!-- Jetty WebApp support -->
169
    <dependency>
170
        <groupId>org.eclipse.jetty</groupId>
171
        <artifactId>jetty-webapp</artifactId>
172
        <version>11.0.0</version>
173
    </dependency>
174
    
175
    <!-- JSP support (if needed) -->
176
    <dependency>
177
        <groupId>org.eclipse.jetty</groupId>
178
        <artifactId>apache-jsp</artifactId>
179
        <version>11.0.0</version>
180
    </dependency>
181
</dependencies>
182
```
183

184
### Custom Tag Library Integration
185

186
Example of integrating custom tag libraries alongside JSTL:
187

188
```java
189
// Create custom tag library JAR
190
File libDir = new File(webAppDir, "WEB-INF/lib");
191
FS.ensureDirExists(libDir);
192
File customTagLibDir = new File("src/main/taglib");
193
JAR.create(customTagLibDir, new File(libDir, "custom-taglib.jar"));
194

195
// Configure context with both JSTL and custom tags
196
JspConfig.init(context, webAppDir.toURI(), scratchDir);
197
```
198

199
## Types
200

201
```java { .api }
202
// Core Jetty types
203
class WebAppContext {
204
    void setAttribute(String name, Object value);
205
    void setWar(String war);
206
    void setResourceBase(String resourceBase);
207
    void setContextPath(String contextPath);
208
    void addConfiguration(Configuration configuration);
209
}
210

211
class Server {
212
    void addConnector(Connector connector);
213
    void setHandler(Handler handler);
214
    void start() throws Exception;
215
    void stop() throws Exception;
216
}
217

218
class ServerConnector {
219
    ServerConnector(Server server);
220
    void setPort(int port);
221
    int getLocalPort();
222
    String getHost();
223
}
224

225
// Standard Java types
226
class URI {
227
    String toASCIIString();
228
}
229

230
class File {
231
    URI toURI();
232
    // Standard file operations
233
}
234
```
235

236
## Error Handling
237

238
Common integration issues and solutions:
239

240
- **ClassNotFoundException**: Ensure JSTL JARs are in the container include pattern
241
- **JSP Compilation Errors**: Verify scratch directory is writable and has sufficient space
242
- **Tag Library Not Found**: Check that taglib URI declarations match the JSTL standard URIs
243
- **Module Loading Failures**: Verify the apache-jstl module is properly installed in Jetty's modules directory