0
# Resource Model
1

2
Runtime representation and processing of JAX-RS resources, including model validation, method invocation, parameter handling, and complete metadata about resources and their methods for routing and execution. The resource model system provides the foundation for Jersey's request routing and method dispatch.
3

4
## Capabilities
5

6
### Resource
7

8
Core resource representation providing programmatic resource construction and factory methods for creating resources from classes or paths.
9

10
```java { .api }
11
/**
12
 * Resource representation providing programmatic resource construction capabilities.
13
 */
14
public final class Resource implements Routed, ResourceModelComponent {
15
    
16
    // Factory methods for creating resource builders
17
    /**
18
     * Create an unbound resource builder.
19
     * @return Resource.Builder instance
20
     */
21
    public static Builder builder();
22
    
23
    /**
24
     * Create a resource builder with specified path.
25
     * @param path Resource path template
26
     * @return Resource.Builder instance with path set
27
     */
28
    public static Builder builder(String path);
29
    
30
    /**
31
     * Create a resource builder from annotated resource class.
32
     * @param resourceClass JAX-RS annotated resource class
33
     * @return Resource.Builder instance initialized from class
34
     */
35
    public static Builder builder(Class<?> resourceClass);
36
    
37
    /**
38
     * Create a resource builder from resource class with validation control.
39
     * @param resourceClass JAX-RS annotated resource class
40
     * @param disableValidation Whether to disable validation
41
     * @return Resource.Builder instance initialized from class
42
     */
43
    public static Builder builder(Class<?> resourceClass, boolean disableValidation);
44
    
45
    /**
46
     * Create a resource builder from existing resource.
47
     * @param resource Existing resource to copy
48
     * @return Resource.Builder instance initialized from resource
49
     */
50
    public static Builder builder(Resource resource);
51
    
52
    // Direct resource creation methods
53
    /**
54
     * Create resource directly from annotated class.
55
     * @param resourceClass JAX-RS annotated resource class
56
     * @return Resource instance created from class
57
     */
58
    public static Resource from(Class<?> resourceClass);
59
    
60
    /**
61
     * Create resource from class with validation control.
62
     * @param resourceClass JAX-RS annotated resource class
63
     * @param disableValidation Whether to disable validation
64
     * @return Resource instance created from class
65
     */
66
    public static Resource from(Class<?> resourceClass, boolean disableValidation);
67
    
68
    // Utility methods
69
    /**
70
     * Check if class is acceptable as JAX-RS resource.
71
     * @param c Class to check
72
     * @return true if class can be used as resource
73
     */
74
    public static boolean isAcceptable(Class<?> c);
75
    
76
    /**
77
     * Get path template from resource class @Path annotation.
78
     * @param resourceClass Resource class with @Path annotation
79
     * @return Path template string or null if no @Path annotation
80
     */
81
    public static String getPath(Class<?> resourceClass);
82
}
83
```
84

85
**Usage Examples:**
86

87
```java
88
import org.glassfish.jersey.server.model.Resource;
89
import jakarta.ws.rs.Path;
90
import jakarta.ws.rs.GET;
91

92
@Path("/users")
93
public class UserResource {
94
    @GET
95
    public String getUsers() {
96
        return "Users list";
97
    }
98
}
99

100
// Create resource from annotated class
101
Resource userResource = Resource.from(UserResource.class);
102

103
// Create resource using builder pattern
104
Resource customResource = Resource.builder("/api/v1/users")
105
    .addMethod("GET")
106
    .handledBy(UserResource.class, "getUsers")
107
    .build();
108

109
// Check if class is valid resource
110
boolean isValid = Resource.isAcceptable(UserResource.class);
111

112
// Get path from class
113
String path = Resource.getPath(UserResource.class); // Returns "/users"
114
```
115

116
### Resource.Builder
117

118
Builder for programmatic resource construction with method handling, child resources, and validation control.
119

120
```java { .api }
121
/**
122
 * Builder for constructing Resource instances programmatically.
123
 */
124
public static final class Builder {
125
    
126
    // Method management
127
    /**
128
     * Add resource method to the resource being built.
129
     * @param resourceMethod ResourceMethod to add
130
     * @return Builder instance for chaining
131
     */
132
    public Builder addMethod(ResourceMethod resourceMethod);
133
    
134
    /**
135
     * Add HTTP method handler to the resource.
136
     * @param httpMethod HTTP method (GET, POST, etc.)
137
     * @return ResourceMethod.Builder for configuring the method
138
     */
139
    public ResourceMethod.Builder addMethod(String httpMethod);
140
    
141
    /**
142
     * Update/replace existing resource method.
143
     * @param resourceMethod ResourceMethod to update
144
     * @return Builder instance for chaining
145
     */
146
    public Builder updateMethod(ResourceMethod resourceMethod);
147
    
148
    // Child resource management
149
    /**
150
     * Add child resource to this resource.
151
     * @param resource Child Resource to add
152
     * @return Builder instance for chaining
153
     */
154
    public Builder addChildResource(Resource resource);
155
    
156
    /**
157
     * Replace existing child resource.
158
     * @param replacedResource Resource to replace
159
     * @param newResource New resource to add
160
     * @return Builder instance for chaining
161
     */
162
    public Builder replaceChildResource(Resource replacedResource, Resource newResource);
163
    
164
    // Resource merging
165
    /**
166
     * Merge this resource with another resource.
167
     * @param resource Resource to merge with
168
     * @return Builder instance for chaining
169
     */
170
    public Builder mergeWith(Resource resource);
171
    
172
    /**
173
     * Merge this resource with another builder.
174
     * @param resourceBuilder Builder to merge with
175
     * @return Builder instance for chaining
176
     */
177
    public Builder mergeWith(Builder resourceBuilder);
178
    
179
    // Configuration
180
    /**
181
     * Mark resource as extended resource.
182
     * @param extended Whether resource is extended
183
     * @return Builder instance for chaining
184
     */
185
    public Builder extended(boolean extended);
186
    
187
    /**
188
     * Set resource path template.
189
     * @param path Path template for the resource
190
     * @return Builder instance for chaining
191
     */
192
    public Builder path(String path);
193
    
194
    /**
195
     * Build the resource instance.
196
     * @return Constructed Resource instance
197
     * @throws IllegalStateException if resource configuration is invalid
198
     */
199
    public Resource build();
200
}
201
```
202

203
**Usage Examples:**
204

205
```java
206
import org.glassfish.jersey.server.model.Resource;
207
import org.glassfish.jersey.server.model.ResourceMethod;
208

209
// Build complex resource programmatically
210
Resource apiResource = Resource.builder("/api/v1/users")
211
    .addMethod("GET")
212
        .handledBy(UserResource.class, "getAllUsers")
213
        .build()
214
    .addMethod("POST")
215
        .handledBy(UserResource.class, "createUser")
216
        .consumes("application/json")
217
        .build()
218
    .addChildResource(
219
        Resource.builder("/{id}")
220
            .addMethod("GET")
221
                .handledBy(UserResource.class, "getUser")
222
                .build()
223
            .build()
224
    )
225
    .build();
226

227
// Merge resources
228
Resource baseResource = Resource.from(BaseResource.class);
229
Resource extendedResource = Resource.builder()
230
    .mergeWith(baseResource)
231
    .addMethod("PUT")
232
        .handledBy(ExtendedResource.class, "updateResource")
233
        .build()
234
    .build();
235
```
236

237
### ResourceModel
238

239
Complete resource model representation containing all registered resources and their metadata for runtime processing.
240

241
```java { .api }
242
/**
243
 * Resource model encapsulating the complete resource information for a JAX-RS application.
244
 * Contains all resources, sub-resources, and their associated metadata.
245
 */
246
public final class ResourceModel implements ResourceModelComponent {
247
    
248
    /**
249
     * Create a new resource model builder.
250
     * @return ResourceModel.Builder instance
251
     */
252
    public static Builder builder();
253
    
254
    /**
255
     * Create a new resource model builder with automatic validation.
256
     * @param disableValidation Whether to disable validation during build
257
     * @return ResourceModel.Builder instance
258
     */
259
    public static Builder builder(boolean disableValidation);
260
    
261
    /**
262
     * Get all root resources in this model.
263
     * @return Set of root Resource instances
264
     */
265
    public Set<Resource> getResources();
266
    
267
    /**
268
     * Get all sub-resource models.
269
     * @return Set of sub-resource ResourceModel instances
270
     */
271
    public Set<ResourceModel> getSubResourceModels();
272
    
273
    /**
274
     * Check if the model is empty.
275
     * @return true if model has no resources, false otherwise
276
     */
277
    public boolean isEmpty();
278
    
279
    /**
280
     * Accept a resource model visitor for traversal.
281
     * @param visitor ResourceModelVisitor to accept
282
     */
283
    public void accept(ResourceModelVisitor visitor);
284
    
285
    /**
286
     * Get validation issues found in the model.
287
     * @return List of validation errors
288
     */
289
    public List<ResourceModelIssue> getValidationIssues();
290
}
291
```
292

293
**Usage Examples:**
294

295
```java
296
import org.glassfish.jersey.server.model.ResourceModel;
297
import org.glassfish.jersey.server.model.Resource;
298

299
// Build resource model
300
ResourceModel.Builder builder = ResourceModel.builder();
301
builder.addResource(Resource.from(UserResource.class));
302
builder.addResource(Resource.from(OrderResource.class));
303
ResourceModel model = builder.build();
304

305
// Access resources
306
Set<Resource> resources = model.getResources();
307
for (Resource resource : resources) {
308
    String path = resource.getPath();
309
    List<ResourceMethod> methods = resource.getResourceMethods();
310
}
311

312
// Check for sub-resource models
313
Set<ResourceModel> subModels = model.getSubResourceModels();
314
boolean isEmpty = model.isEmpty();
315

316
// Validate model
317
List<ResourceModelIssue> issues = model.getValidationIssues();
318
if (!issues.isEmpty()) {
319
    for (ResourceModelIssue issue : issues) {
320
        System.err.println("Validation issue: " + issue.getMessage());
321
    }
322
}
323
```
324

325
### ResourceModel.Builder
326

327
Builder for constructing resource models with validation and configuration options.
328

329
```java { .api }
330
/**
331
 * Builder for constructing ResourceModel instances.
332
 */
333
public static final class Builder {
334
    
335
    /**
336
     * Add a resource to the model.
337
     * @param resource Resource to add
338
     * @return Builder instance for chaining
339
     */
340
    public Builder addResource(Resource resource);
341
    
342
    /**
343
     * Add multiple resources to the model.
344
     * @param resources Collection of resources to add
345
     * @return Builder instance for chaining
346
     */
347
    public Builder addResources(Collection<Resource> resources);
348
    
349
    /**
350
     * Build the resource model.
351
     * @return Constructed ResourceModel instance
352
     * @throws ModelValidationException if validation fails
353
     */
354
    public ResourceModel build();
355
    
356
    /**
357
     * Build the resource model with validation control.
358
     * @param validate Whether to validate the model during build
359
     * @return Constructed ResourceModel instance
360
     * @throws ModelValidationException if validation enabled and fails
361
     */
362
    public ResourceModel build(boolean validate);
363
}
364
```
365

366
### RuntimeResource
367

368
Runtime representation of resources providing access to resource metadata and method information at runtime.
369

370
```java { .api }
371
/**
372
 * Runtime resource representation providing resource metadata and method routing information.
373
 */
374
public final class RuntimeResource implements ResourceModelComponent {
375
    
376
    /**
377
     * Get the full resource path including parent paths.
378
     * @return Full resource path
379
     */
380
    public String getFullPath();
381
    
382
    /**
383
     * Get the resource path template.
384
     * @return Path template string
385
     */
386
    public String getPathTemplate();
387
    
388
    /**
389
     * Get all resource methods for this resource.
390
     * @return List of ResourceMethod instances
391
     */
392
    public List<ResourceMethod> getResourceMethods();
393
    
394
    /**
395
     * Get resource method by HTTP method.
396
     * @param httpMethod HTTP method name (GET, POST, etc.)
397
     * @return ResourceMethod for the HTTP method or null if not found
398
     */
399
    public ResourceMethod getResourceMethod(String httpMethod);
400
    
401
    /**
402
     * Get all sub-resource methods.
403
     * @return List of sub-resource ResourceMethod instances
404
     */
405
    public List<ResourceMethod> getSubResourceMethods();
406
    
407
    /**
408
     * Get all sub-resource locators.
409
     * @return List of ResourceMethod instances that are sub-resource locators
410
     */
411
    public List<ResourceMethod> getSubResourceLocators();
412
    
413
    /**
414
     * Get child runtime resources.
415
     * @return List of child RuntimeResource instances
416
     */
417
    public List<RuntimeResource> getChildResources();
418
    
419
    /**
420
     * Get parent runtime resource.
421
     * @return Parent RuntimeResource or null if this is a root resource
422
     */
423
    public RuntimeResource getParent();
424
    
425
    /**
426
     * Get regular expression pattern for path matching.
427
     * @return Pattern for matching resource paths
428
     */
429
    public Pattern getPathPattern();
430
}
431
```
432

433
**Usage Examples:**
434

435
```java
436
import org.glassfish.jersey.server.model.RuntimeResource;
437
import org.glassfish.jersey.server.model.ResourceMethod;
438
import java.util.regex.Pattern;
439

440
// Access runtime resource information
441
RuntimeResource runtimeResource = getRuntimeResource();
442

443
String fullPath = runtimeResource.getFullPath(); // "/api/users/{id}"
444
String pathTemplate = runtimeResource.getPathTemplate(); // "/users/{id}"
445
Pattern pathPattern = runtimeResource.getPathPattern();
446

447
// Access resource methods
448
List<ResourceMethod> methods = runtimeResource.getResourceMethods();
449
ResourceMethod getMethod = runtimeResource.getResourceMethod("GET");
450
ResourceMethod postMethod = runtimeResource.getResourceMethod("POST");
451

452
// Access sub-resources
453
List<ResourceMethod> subResourceMethods = runtimeResource.getSubResourceMethods();
454
List<ResourceMethod> subResourceLocators = runtimeResource.getSubResourceLocators();
455
List<RuntimeResource> childResources = runtimeResource.getChildResources();
456

457
// Navigate resource hierarchy
458
RuntimeResource parent = runtimeResource.getParent();
459
if (parent != null) {
460
    String parentPath = parent.getFullPath();
461
}
462
```
463

464
### RuntimeResourceModel
465

466
Container for runtime resource models providing organized access to all runtime resources.
467

468
```java { .api }
469
/**
470
 * Container for runtime resource models providing organized access to runtime resources.
471
 */
472
public final class RuntimeResourceModel {
473
    
474
    /**
475
     * Get all runtime resources in the model.
476
     * @return List of all RuntimeResource instances
477
     */
478
    public List<RuntimeResource> getRuntimeResources();
479
    
480
    /**
481
     * Get runtime resources organized by path patterns.
482
     * @return Map of path patterns to RuntimeResource lists
483
     */
484
    public Map<Pattern, List<RuntimeResource>> getResourcesByPattern();
485
    
486
    /**
487
     * Find runtime resource by path.
488
     * @param path Resource path to find
489
     * @return RuntimeResource matching the path or null
490
     */
491
    public RuntimeResource findRuntimeResource(String path);
492
    
493
    /**
494
     * Check if the model is empty.
495
     * @return true if no runtime resources exist
496
     */
497
    public boolean isEmpty();
498
}
499
```
500

501
### ModelProcessor
502

503
Interface for processing and transforming resource models during application initialization.
504

505
```java { .api }
506
/**
507
 * Interface for processing resource models during application startup.
508
 * Allows customization and transformation of the resource model.
509
 */
510
public interface ModelProcessor {
511
    
512
    /**
513
     * Process the main resource model.
514
     * @param resourceModel Resource model to process
515
     * @param configuration Application configuration
516
     * @return Processed resource model (may be the same or a new instance)
517
     */
518
    ResourceModel processResourceModel(ResourceModel resourceModel, Configuration configuration);
519
    
520
    /**
521
     * Process a sub-resource model.
522
     * @param subResourceModel Sub-resource model to process
523
     * @param configuration Application configuration
524
     * @return Processed sub-resource model (may be the same or a new instance)
525
     */
526
    ResourceModel processSubResource(ResourceModel subResourceModel, Configuration configuration);
527
}
528
```
529

530
**Usage Examples:**
531

532
```java
533
import org.glassfish.jersey.server.model.ModelProcessor;
534
import org.glassfish.jersey.server.model.ResourceModel;
535
import jakarta.ws.rs.core.Configuration;
536

537
// Custom model processor implementation
538
public class CustomModelProcessor implements ModelProcessor {
539
    
540
    @Override
541
    public ResourceModel processResourceModel(ResourceModel resourceModel, Configuration configuration) {
542
        // Add custom validation
543
        validateCustomRules(resourceModel);
544
        
545
        // Transform model if needed
546
        ResourceModel.Builder builder = ResourceModel.builder();
547
        for (Resource resource : resourceModel.getResources()) {
548
            // Apply transformations
549
            Resource transformedResource = transformResource(resource);
550
            builder.addResource(transformedResource);
551
        }
552
        
553
        return builder.build();
554
    }
555
    
556
    @Override 
557
    public ResourceModel processSubResource(ResourceModel subResourceModel, Configuration configuration) {
558
        // Process sub-resources similarly
559
        return processResourceModel(subResourceModel, configuration);
560
    }
561
    
562
    private void validateCustomRules(ResourceModel model) {
563
        for (Resource resource : model.getResources()) {
564
            // Custom validation logic
565
            if (!isValidResource(resource)) {
566
                throw new ModelValidationException("Invalid resource: " + resource.getPath());
567
            }
568
        }
569
    }
570
}
571
```
572

573
### ResourceMethodInvoker
574

575
Handler for resource method invocation providing the bridge between the resource model and actual method execution.
576

577
```java { .api }
578
/**
579
 * Resource method invoker handling the execution of resource methods.
580
 * Implements Endpoint and ResourceInfo interfaces.
581
 */
582
public final class ResourceMethodInvoker implements Endpoint, ResourceInfo {
583
    
584
    /**
585
     * Get the resource method being invoked.
586
     * @return ResourceMethod instance
587
     */
588
    public ResourceMethod getResourceMethod();
589
    
590
    /**
591
     * Get the resource class containing the method.
592
     * @return Resource class
593
     */
594
    public Class<?> getResourceClass();
595
    
596
    /**
597
     * Get the Java method being invoked.
598
     * @return Method instance
599
     */
600
    public Method getResourceMethod();
601
    
602
    /**
603
     * Check if the method is asynchronous.
604
     * @return true if method supports asynchronous execution
605
     */
606
    public boolean isManagedAsyncDeclared();
607
    
608
    /**
609
     * Check if the method is suspended.
610
     * @return true if method execution is suspended
611
     */
612
    public boolean isSuspendDeclared();
613
    
614
    /**
615
     * Apply the method invocation.
616
     * @param requestContext Request context
617
     * @return Method invocation result
618
     */
619
    public Object apply(ContainerRequest requestContext);
620
}
621
```
622

623
### Parameter
624

625
Method parameter representation providing complete parameter metadata for injection and validation.
626

627
```java { .api }
628
/**
629
 * Server-side parameter representation extending the base Parameter class.
630
 * Provides server-specific parameter information and metadata.
631
 */
632
public class Parameter extends org.glassfish.jersey.model.Parameter implements AnnotatedElement {
633
    
634
    /**
635
     * Parameter source enumeration.
636
     */
637
    public enum Source {
638
        PATH, QUERY, HEADER, COOKIE, FORM, MATRIX, BEAN_PARAM, CONTEXT, ENTITY, UNKNOWN
639
    }
640
    
641
    /**
642
     * Get the parameter source.
643
     * @return Parameter source type
644
     */
645
    public Source getSource();
646
    
647
    /**
648
     * Get the parameter source name.
649
     * @return Source name (query parameter name, path parameter name, etc.)
650
     */
651
    public String getSourceName();
652
    
653
    /**
654
     * Check if parameter has a default value.
655
     * @return true if default value is specified
656
     */
657
    public boolean hasDefaultValue();
658
    
659
    /**
660
     * Get the parameter default value.
661
     * @return Default value string or null
662
     */
663
    public String getDefaultValue();
664
    
665
    /**
666
     * Check if parameter is encoded.
667
     * @return true if parameter value should not be decoded
668
     */
669
    public boolean isEncoded();
670
    
671
    /**
672
     * Get parameter annotations.
673
     * @return Array of parameter annotations
674
     */
675
    public Annotation[] getAnnotations();
676
    
677
    /**
678
     * Get parameter type.
679
     * @return Parameter class type
680
     */
681
    public Class<?> getRawType();
682
    
683
    /**
684
     * Get parameter generic type.
685
     * @return Parameter generic type
686
     */
687
    public Type getType();
688
}
689
```
690

691
**Usage Examples:**
692

693
```java
694
import org.glassfish.jersey.server.model.Parameter;
695
import java.lang.annotation.Annotation;
696
import java.lang.reflect.Type;
697

698
// Access parameter information
699
Parameter parameter = getMethodParameter();
700

701
Parameter.Source source = parameter.getSource(); // PATH, QUERY, etc.
702
String sourceName = parameter.getSourceName(); // "id", "name", etc.
703
boolean hasDefault = parameter.hasDefaultValue();
704
String defaultValue = parameter.getDefaultValue();
705

706
// Type information
707
Class<?> rawType = parameter.getRawType(); // String.class, Integer.class, etc.
708
Type genericType = parameter.getType(); // For generic types like List<String>
709

710
// Annotations
711
Annotation[] annotations = parameter.getAnnotations();
712
for (Annotation annotation : annotations) {
713
    if (annotation instanceof PathParam) {
714
        PathParam pathParam = (PathParam) annotation;
715
        String pathParamValue = pathParam.value();
716
    }
717
}
718

719
// Encoding information
720
boolean isEncoded = parameter.isEncoded();
721
```
722

723
### Model Validation
724

725
Exception handling and validation for resource models.
726

727
```java { .api }
728
/**
729
 * Exception thrown when resource model validation fails.
730
 */
731
public class ModelValidationException extends RuntimeException {
732
    
733
    /**
734
     * Create validation exception with message.
735
     * @param message Error message
736
     */
737
    public ModelValidationException(String message);
738
    
739
    /**
740
     * Create validation exception with message and cause.
741
     * @param message Error message
742
     * @param cause Underlying cause
743
     */
744
    public ModelValidationException(String message, Throwable cause);
745
    
746
    /**
747
     * Get validation issues.
748
     * @return List of validation issues that caused the exception
749
     */
750
    public List<ResourceModelIssue> getIssues();
751
}
752

753
/**
754
 * Individual resource model validation issue.
755
 */
756
public final class ResourceModelIssue {
757
    
758
    /**
759
     * Get issue severity level.
760
     * @return Severity (ERROR, WARNING, INFO)
761
     */
762
    public Severity getSeverity();
763
    
764
    /**
765
     * Get issue message.
766
     * @return Descriptive error message
767
     */
768
    public String getMessage();
769
    
770
    /**
771
     * Get the source object that caused the issue.
772
     * @return Source object (Resource, ResourceMethod, etc.)
773
     */
774
    public Object getSource();
775
}
776
```