0
# Jersey Server
1

2
Jersey Server is the core server implementation component of Eclipse Jersey, a comprehensive JAX-RS (Jakarta RESTful Web Services 3.1) reference implementation framework. This library provides essential server-side functionality for building RESTful web services in Java, including resource configuration, request/response processing, content negotiation, dependency injection through HK2, validation support, and extensible provider mechanisms.
3

4
## Package Information
5

6
- **Package Name**: jersey-server
7
- **Package Coordinates**: org.glassfish.jersey.core:jersey-server
8
- **Package Type**: Maven
9
- **Language**: Java
10
- **Installation**: Add to Maven pom.xml:
11

12
```xml
13
<dependency>
14
    <groupId>org.glassfish.jersey.core</groupId>
15
    <artifactId>jersey-server</artifactId>
16
    <version>3.1.10</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import org.glassfish.jersey.server.ResourceConfig;
24
import org.glassfish.jersey.server.ApplicationHandler;
25
import org.glassfish.jersey.server.ContainerRequest;
26
import org.glassfish.jersey.server.ContainerResponse;
27
```
28

29
## Basic Usage
30

31
```java
32
import org.glassfish.jersey.server.ResourceConfig;
33
import org.glassfish.jersey.server.ApplicationHandler;
34
import jakarta.ws.rs.GET;
35
import jakarta.ws.rs.Path;
36
import jakarta.ws.rs.Produces;
37
import jakarta.ws.rs.core.MediaType;
38

39
// Define a simple resource
40
@Path("/hello")
41
public class HelloWorldResource {
42
    @GET
43
    @Produces(MediaType.TEXT_PLAIN)
44
    public String sayHello() {
45
        return "Hello, World!";
46
    }
47
}
48

49
// Configure and initialize Jersey server
50
ResourceConfig config = new ResourceConfig();
51
config.register(HelloWorldResource.class);
52

53
// Create application handler for request processing  
54
ApplicationHandler app = new ApplicationHandler(config);
55

56
// Enable package scanning for resources
57
ResourceConfig scanConfig = new ResourceConfig();
58
scanConfig.packages("com.example.resources");
59

60
// Register multiple resources at once
61
ResourceConfig multiConfig = new ResourceConfig();
62
multiConfig.registerClasses(HelloWorldResource.class, OtherResource.class);
63
```
64

65
## Architecture
66

67
Jersey Server is built around several key architectural components:
68

69
- **ResourceConfig**: Central configuration class that manages resource registration, provider configuration, and feature enablement
70
- **ApplicationHandler**: Core request processing engine that handles the complete request lifecycle from routing to response generation
71
- **Container Integration**: Pluggable container model supporting various deployment environments (Servlet, Grizzly, Netty, etc.)
72
- **Resource Model**: Runtime representation of JAX-RS resources with complete metadata for method routing and parameter injection
73
- **Service Provider Interface (SPI)**: Extensive extension points for customizing container behavior, validation, monitoring, and lifecycle management
74
- **Monitoring System**: Comprehensive application and request-level monitoring with JMX integration and event-driven statistics collection
75

76
## Capabilities
77

78
### Resource Configuration
79

80
Primary configuration class for Jersey server applications, providing resource registration, property management, package scanning, and feature configuration. Essential for setting up any Jersey server application.
81

82
```java { .api }
83
public class ResourceConfig extends Application 
84
    implements Configurable<ResourceConfig>, ServerConfig, ApplicationSupplier {
85
    
86
    // Constructors
87
    public ResourceConfig();
88
    public ResourceConfig(Set<Class<?>> classes);
89
    public ResourceConfig(Class<?>... classes);
90
    public ResourceConfig(ResourceConfig original);
91
    
92
    // Resource registration
93
    public ResourceConfig register(Class<?> componentClass);
94
    public ResourceConfig register(Object component);
95
    public ResourceConfig registerClasses(Set<Class<?>> classes);
96
    public ResourceConfig registerClasses(Class<?>... classes);
97
    
98
    // Package scanning
99
    public ResourceConfig packages(String... packages);
100
    public ResourceConfig packages(boolean recursive, String... packages);
101
    
102
    // Property management
103
    public ResourceConfig property(String name, Object value);
104
    public ResourceConfig setProperties(Map<String, ?> properties);
105
}
106
```
107

108
[Resource Configuration](./resource-configuration.md)
109

110
### Request Processing
111

112
Core request processing functionality including the main application handler, container request/response objects, and lifecycle management. Handles the complete request flow from HTTP input to JAX-RS resource method execution.
113

114
```java { .api }
115
public final class ApplicationHandler {
116
    public ApplicationHandler(Application application);
117
    public ApplicationHandler(Class<? extends Application> applicationClass);
118
    
119
    public Future<ContainerResponse> apply(ContainerRequest requestContext);
120
    public Future<ContainerResponse> apply(ContainerRequest requestContext, 
121
                                         OutputStream entityStream);
122
}
123

124
public class ContainerRequest extends InboundMessageContext 
125
    implements ContainerRequestContext {
126
    public ContainerRequest(URI baseUri, URI requestUri, String httpMethod,
127
                          SecurityContext securityContext, PropertiesDelegate propertiesDelegate);
128
}
129

130
public class ContainerResponse implements ContainerResponseContext {
131
    public ContainerResponse(ContainerRequest requestContext, Response response);
132
}
133
```
134

135
[Request Processing](./request-processing.md)
136

137
### Resource Model
138

139
Runtime representation and processing of JAX-RS resources, including model validation, method invocation, and parameter handling. Provides complete metadata about resources and their methods for routing and execution.
140

141
```java { .api }
142
public final class ResourceModel implements ResourceModelComponent {
143
    public static Builder builder();
144
    public Set<Resource> getResources();
145
    public Set<ResourceModel> getSubResourceModels();
146
}
147

148
public interface ModelProcessor {
149
    ResourceModel processResourceModel(ResourceModel resourceModel, Configuration configuration);
150
    ResourceModel processSubResource(ResourceModel subResourceModel, Configuration configuration);
151
}
152

153
public class Parameter extends org.glassfish.jersey.model.Parameter implements AnnotatedElement {
154
    public Source getSource();
155
    public String getSourceName();
156
    public boolean hasDefaultValue();
157
    public String getDefaultValue();
158
}
159
```
160

161
[Resource Model](./resource-model.md)
162

163
### Asynchronous Processing
164

165
Server-side asynchronous request processing including async contexts, chunked output, broadcasting, and managed async execution. Enables scalable handling of long-running operations and streaming responses.
166

167
```java { .api }
168
public interface AsyncContext extends AsyncResponse {
169
    ContainerRequest getContainerRequest();
170
    ContainerResponse getContainerResponse();
171
}
172

173
public class ChunkedOutput<T> extends GenericType<T> implements Closeable {
174
    public ChunkedOutput(Type chunkType);
175
    public boolean isClosed();
176
    public void write(T chunk) throws IOException;
177
    public void close() throws IOException;
178
}
179

180
public final class Broadcaster<T> implements BroadcasterListener<T> {
181
    public static <T> Broadcaster<T> createOnly(Class<T> chunkType);
182
    public void add(ChunkedOutput<T> chunkedOutput);
183
    public boolean remove(ChunkedOutput<T> chunkedOutput);
184
    public void broadcast(T chunk);
185
}
186
```
187

188
[Asynchronous Processing](./async-processing.md)
189

190
### Service Provider Interface (SPI)
191

192
Extension points for container integration, component management, request scoping, validation, and lifecycle management. Enables deep customization of Jersey server behavior and integration with external frameworks.
193

194
```java { .api }
195
public interface Container {
196
    void reload();
197
    void reload(ResourceConfig configuration);
198
    ApplicationHandler getApplicationHandler();
199
    ResourceConfig getConfiguration();
200
}
201

202
public interface ContainerProvider {
203
    <T> T createContainer(Class<T> type, Application application);
204
}
205

206
public interface ComponentProvider extends org.glassfish.jersey.spi.ComponentProvider {
207
    void initialize(InjectionManager injectionManager);
208
}
209

210
public interface ExternalRequestScope<T> extends AutoCloseable {
211
    ExternalRequestContext<T> open();
212
}
213
```
214

215
[Service Provider Interface](./spi.md)
216

217
### Monitoring and Statistics
218

219
Comprehensive monitoring system with application-level and request-level event handling, statistics collection, JMX integration, and performance metrics. Provides detailed insights into application performance and behavior.
220

221
```java { .api }
222
public interface ApplicationEventListener {
223
    void onEvent(ApplicationEvent event);
224
    RequestEventListener onRequest(RequestEvent requestEvent);
225
}
226

227
public interface MonitoringStatistics {
228
    ExecutionStatistics getRequestStatistics();
229
    ResponseStatistics getResponseStatistics();
230
    Map<String, ResourceStatistics> getUriStatistics();
231
    Map<Class<?>, ExceptionMapperStatistics> getExceptionMapperStatistics();
232
}
233

234
public interface ExecutionStatistics {
235
    long getTimeWindowSize();
236
    TimeUnit getTimeWindowSizeUnit();
237
    TimeWindowStatistics getTimeWindowStatistics();
238
}
239
```
240

241
[Monitoring and Statistics](./monitoring.md)
242

243
### WADL Support
244

245
Web Application Description Language (WADL) generation and configuration for automatic API documentation. Provides machine-readable descriptions of RESTful web services.
246

247
```java { .api }
248
public interface WadlApplicationContext {
249
    Application getApplication();
250
    Grammars getGrammars();
251
    void setWadlGenerationEnabled(boolean wadlGenerationEnabled);
252
}
253

254
public interface WadlGenerator {
255
    Application createApplication();
256
    Resources createResources();
257
    Resource createResource(org.glassfish.jersey.server.model.Resource resource, String path);
258
}
259

260
public class WadlFeature implements Feature {
261
    public boolean configure(FeatureContext context);
262
}
263
```
264

265
[WADL Support](./wadl.md)
266

267
### Configuration Properties
268

269
Server configuration constants for customizing Jersey server behavior including provider scanning, feature control, validation settings, and performance tuning options.
270

271
```java { .api }
272
public final class ServerProperties {
273
    // Provider scanning
274
    public static final String PROVIDER_PACKAGES = "jersey.config.server.provider.packages";
275
    public static final String PROVIDER_SCANNING_RECURSIVE = "jersey.config.server.provider.scanning.recursive";
276
    public static final String PROVIDER_CLASSPATH = "jersey.config.server.provider.classpath";
277
    
278
    // Feature control
279
    public static final String FEATURE_AUTO_DISCOVERY_DISABLE = "jersey.config.server.disableAutoDiscovery";
280
    public static final String WADL_FEATURE_DISABLE = "jersey.config.server.wadl.disableWadl";
281
    public static final String BV_FEATURE_DISABLE = "jersey.config.beanValidation.disable.server";
282
    
283
    // Advanced configuration
284
    public static final String OUTBOUND_CONTENT_LENGTH_BUFFER = "jersey.config.server.contentLength.buffer";
285
    public static final String REDUCE_CONTEXT_PATH_SLASHES_ENABLED = "jersey.config.server.reduceContextPathSlashesEnabled";
286
}
287
```
288

289
[Configuration Properties](./configuration-properties.md)