0
# Eclipse Jetty Servlet
1

2
Eclipse Jetty servlet container provides comprehensive servlet, filter, and listener integration with lifecycle management and dynamic registration support. It offers a complete implementation of the Jakarta Servlet specification with embedded server capabilities, programmatic configuration, and extensive testing utilities.
3

4
## Package Information
5

6
- **Package Name**: org.eclipse.jetty:jetty-servlet
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.eclipse.jetty</groupId>
13
    <artifactId>jetty-servlet</artifactId>
14
    <version>11.0.25</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
// Core servlet handling
22
import org.eclipse.jetty.servlet.ServletContextHandler;
23
import org.eclipse.jetty.servlet.ServletHandler;
24
import org.eclipse.jetty.servlet.ServletHolder;
25

26
// Filter management
27
import org.eclipse.jetty.servlet.FilterHolder;
28
import org.eclipse.jetty.servlet.FilterMapping;
29

30
// Context and lifecycle
31
import org.eclipse.jetty.servlet.Source;
32
import org.eclipse.jetty.server.Handler;
33

34
// Jakarta Servlet API
35
import jakarta.servlet.Servlet;
36
import jakarta.servlet.Filter;
37
import jakarta.servlet.DispatcherType;
38
```
39

40
## Basic Usage
41

42
```java
43
import org.eclipse.jetty.servlet.ServletContextHandler;
44
import org.eclipse.jetty.servlet.ServletHolder;
45
import org.eclipse.jetty.server.Server;
46
import jakarta.servlet.http.HttpServlet;
47
import jakarta.servlet.http.HttpServletRequest;
48
import jakarta.servlet.http.HttpServletResponse;
49

50
// Create a simple servlet
51
public class HelloServlet extends HttpServlet {
52
    @Override
53
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) 
54
            throws IOException {
55
        resp.getWriter().println("Hello, World!");
56
    }
57
}
58

59
// Configure servlet context with embedded server
60
Server server = new Server(8080);
61

62
ServletContextHandler context = new ServletContextHandler("/myapp");
63
context.addServlet(HelloServlet.class, "/hello");
64

65
server.setHandler(context);
66
server.start();
67
```
68

69
## Architecture
70

71
The Jetty servlet module follows a hierarchical handler structure:
72

73
- **ServletContextHandler**: Top-level context managing servlets, filters, and listeners
74
- **ServletHandler**: Core handler for servlet mapping and lifecycle
75
- **Holders**: Wrapper classes (ServletHolder, FilterHolder, ListenerHolder) managing component instances
76
- **Mappings**: URL pattern to component associations (ServletMapping, FilterMapping)
77
- **Source**: Origin tracking for components (embedded, descriptor, annotation)
78

79
## Capabilities
80

81
### Servlet Context Management
82

83
Create and configure servlet contexts with comprehensive session, security, and error handling support.
84

85
```java { .api }
86
public class ServletContextHandler extends ContextHandler {
87
    public static final int SESSIONS = 1;
88
    public static final int SECURITY = 2;
89
    public static final int NO_SESSIONS = 0;
90
    public static final int NO_SECURITY = 0;
91
    
92
    public ServletContextHandler();
93
    public ServletContextHandler(int options);
94
    public ServletContextHandler(HandlerContainer parent, String contextPath);
95
    public ServletContextHandler(HandlerContainer parent, String contextPath, int options);
96
    
97
    public ServletHolder addServlet(String className, String pathSpec);
98
    public ServletHolder addServlet(Class<? extends Servlet> servlet, String pathSpec);
99
    public void addServlet(ServletHolder servlet, String pathSpec);
100
    
101
    public FilterHolder addFilter(Class<? extends Filter> filterClass, String pathSpec, 
102
                                  EnumSet<DispatcherType> dispatches);
103
    public ServletHandler getServletHandler();
104
    public SessionHandler getSessionHandler();
105
    public SecurityHandler getSecurityHandler();
106
}
107
```
108

109
[Servlet Context Management](./servlet-context.md)
110

111
### Servlet Handling
112

113
Manage servlet lifecycle, registration, and URL pattern mapping with comprehensive configuration options.
114

115
```java { .api }
116
public class ServletHandler extends ScopedHandler {
117
    public ServletHolder[] getServlets();
118
    public ServletMapping[] getServletMappings();
119
    public ServletHolder newServletHolder(Source source);
120
    public ServletHolder getServlet(String name);
121
    public ServletHolder addServletWithMapping(String className, String pathSpec);
122
    public ServletHolder addServletWithMapping(Class<? extends Servlet> servlet, String pathSpec);
123
    public void addServlet(ServletHolder servletHolder);
124
    public void addServletMapping(ServletMapping servletMapping);
125
}
126

127
public class ServletHolder extends Holder<Servlet> {
128
    public ServletHolder();
129
    public ServletHolder(String name, Class<? extends Servlet> servlet);
130
    public ServletHolder(String name, Servlet servlet);
131
    
132
    public void setServlet(Servlet servlet);
133
    public Servlet getServlet();
134
    public int getInitOrder();
135
    public void setInitOrder(int order);
136
    public boolean isEnabled();
137
    public void setEnabled(boolean enabled);
138
}
139
```
140

141
[Servlet Handling](./servlet-handling.md)
142

143
### Filter Handling
144

145
Configure request/response filtering with dispatcher type control and URL pattern matching.
146

147
```java { .api }
148
public class FilterHolder extends Holder<Filter> {
149
    public FilterHolder();
150
    public FilterHolder(Class<? extends Filter> filter);
151
    public FilterHolder(Filter filter);
152
    
153
    public void setFilter(Filter filter);
154
    public Filter getFilter();
155
    public FilterRegistration.Dynamic getRegistration();
156
}
157

158
public class FilterMapping implements Dumpable {
159
    public static final int REQUEST = 1;
160
    public static final int FORWARD = 2;
161
    public static final int INCLUDE = 4;
162
    public static final int ERROR = 8;
163
    public static final int ASYNC = 16;
164
    public static final int ALL = 31;
165
    
166
    public String getFilterName();
167
    public void setFilterName(String filterName);
168
    public String[] getPathSpecs();
169
    public void setPathSpecs(String[] pathSpecs);
170
    public EnumSet<DispatcherType> getDispatcherTypes();
171
    public void setDispatcherTypes(EnumSet<DispatcherType> dispatcherTypes);
172
}
173
```
174

175
[Filter Handling](./filter-handling.md)
176

177
### Listener Management
178

179
Handle servlet context events and lifecycle callbacks with decoration capabilities.
180

181
```java { .api }
182
public class ListenerHolder extends BaseHolder<EventListener> {
183
    public ListenerHolder();
184
    public ListenerHolder(Source source);
185
    public ListenerHolder(Class<? extends EventListener> listener);
186
    
187
    public void setListener(EventListener listener);
188
    public EventListener getListener();
189
}
190

191
public class DecoratingListener implements ServletContextAttributeListener {
192
    public DecoratingListener(ServletContextHandler context, String attributeName);
193
    
194
    public void attributeAdded(ServletContextAttributeEvent event);
195
    public void attributeRemoved(ServletContextAttributeEvent event);
196
    public void attributeReplaced(ServletContextAttributeEvent event);
197
}
198
```
199

200
[Listener Management](./listeners.md)
201

202
### Error Handling
203

204
Map HTTP errors and exceptions to custom error pages with comprehensive error response management.
205

206
```java { .api }
207
public class ErrorPageErrorHandler extends ErrorHandler 
208
        implements ErrorHandler.ErrorPageMapper {
209
    public ErrorPageErrorHandler();
210
    
211
    public String getErrorPage(HttpServletRequest request);
212
    public void addErrorPage(String pathSpec, String error);
213
    public void addErrorPage(int code, String error);
214
    public void addErrorPage(Class<? extends Throwable> exception, String error);
215
    public Map<String, String> getErrorPages();
216
    public void setErrorPages(Map<String, String> errorPages);
217
}
218
```
219

220
[Error Handling](./error-handling.md)
221

222
### Testing Utilities
223

224
Comprehensive testing framework for servlets without requiring a full server deployment.
225

226
```java { .api }
227
public class ServletTester extends ContainerLifeCycle {
228
    public ServletTester();
229
    public ServletTester(String contextPath);
230
    
231
    public ServletContextHandler getContext();
232
    public void setContextPath(String contextPath);
233
    public String getContextPath();
234
    public void addServlet(Class<? extends Servlet> servlet, String pathSpec);
235
    public ServletHolder addServlet(String className, String pathSpec);
236
    public void addFilter(Class<? extends Filter> filter, String pathSpec, 
237
                          EnumSet<DispatcherType> dispatches);
238
    public String getResponses(String request);
239
    public String getResponses(String request, long idleFor, TimeUnit units);
240
}
241
```
242

243
[Testing Utilities](./testing.md)
244

245
### Monitoring and Statistics
246

247
Server monitoring capabilities with JMX support and comprehensive statistics reporting.
248

249
```java { .api }
250
public class StatisticsServlet extends HttpServlet {
251
    public StatisticsServlet();
252
    
253
    public void init(ServletConfig config);
254
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
255
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
256
}
257
```
258

259
[Monitoring and Statistics](./monitoring.md)
260

261
## Core Types
262

263
```java { .api }
264
public abstract class BaseHolder<T> extends AbstractLifeCycle implements Dumpable {
265
    public enum Source {
266
        EMBEDDED, JAKARTA_API, DESCRIPTOR, ANNOTATION
267
    }
268
    
269
    public Source getSource();
270
    public void initialize();
271
    public String getClassName();
272
    public Class<? extends T> getHeldClass();
273
    public ServletHandler getServletHandler();
274
    public void setServletHandler(ServletHandler servletHandler);
275
    public void setClassName(String className);
276
    public void setHeldClass(Class<? extends T> held);
277
}
278

279
public abstract class Holder<T> extends BaseHolder<T> {
280
    public String getDisplayName();
281
    public String getInitParameter(String param);
282
    public Enumeration<String> getInitParameterNames();
283
    public Map<String, String> getInitParameters();
284
    public String getName();
285
    public void setDisplayName(String name);
286
    public void setInitParameter(String param, String value);
287
    public void setInitParameters(Map<String, String> map);
288
    public void setName(String name);
289
    public void setAsyncSupported(boolean suspendable);
290
    public boolean isAsyncSupported();
291
}
292

293
public class ServletMapping {
294
    public ServletMapping();
295
    public ServletMapping(Source source);
296
    
297
    public String[] getPathSpecs();
298
    public void setPathSpecs(String[] pathSpecs);
299
    public void setPathSpec(String pathSpec);
300
    public String getServletName();
301
    public void setServletName(String servletName);
302
    public Source getSource();
303
}
304

305
public class Source {
306
    public static final Source EMBEDDED = new Source(Origin.EMBEDDED, null);
307
    public static final Source JAVAX_API = new Source(Origin.JAKARTA_API, null);
308
    
309
    public enum Origin { EMBEDDED, JAKARTA_API, DESCRIPTOR, ANNOTATION }
310
    
311
    public Source(Origin o, String resource);
312
    public Origin getOrigin();
313
    public String getResource();
314
}
315
```