org.glassfish.jersey.server.model
Class Resource

java.lang.Object
  org.glassfish.jersey.server.model.Resource

All Implemented Interfaces:

ResourceModelComponent, Routed

public final class Resource
extends Object
implements Routed, ResourceModelComponent

Model of a single resource component.

Resource component model represents a collection of methods grouped under the same parent request path template. Resource class is also the main entry point to the programmatic resource modeling API that provides ability to programmatically extend the existing JAX-RS annotated resource classes or build new resource models that may be utilized by Jersey runtime.

For example:

 @Path("hello")
 public class HelloResource {
      @GET
      @Produces("text/plain")
      public String sayHello() {
          return "Hello!";
      }
 }

 ...

 // Register the annotated resource.
 ResourceConfig resourceConfig = new ResourceConfig(HelloResource.class);

 // Add new "hello2" resource using the annotated resource class
 // and overriding the resource path.
 Resource.Builder resourceBuilder =
         Resource.builder(HelloResource.class, new LinkedList<ResourceModelIssue>())
         .path("hello2");

 // Add a new (virtual) sub-resource method to the "hello2" resource.
 resourceBuilder.addMethod("GET")
         .path("world")
         .produces("text/plain")
         .handledBy(new Inflector<Request, String>() {
                 @Override
                 public String apply(Request request) {
                     return "Hello World!";
                 }
         });

 // Register the new programmatic resource in the application's configuration.
 resourceConfig.addResources(resourceBuilder.build());
 

The following table illustrates the supported requests and provided responses for the application configured in the example above.

Request	Response	Method invoked
"GET /hello"	"Hello!"	HelloResource.sayHello()
"GET /hello2"	"Hello!"	HelloResource.sayHello()
"GET /hello2/world"	"Hello World!"	Inflector.apply()

Author:

Marek Potociar (marek.potociar at oracle.com)

Nested Class Summary

static class

Resource.Builder Resource model component builder.

Method Summary

void	accept(ResourceModelVisitor visitor) A component should call the visitor back with an appropriate visitor interface method to give it a chance to process.
static Resource.Builder	builder() Get a new unbound resource model builder.
static Resource.Builder	builder(Class<?> resourceClass) Create a resource model builder initialized by introspecting an annotated JAX-RS resource class.
static Resource.Builder	builder(Object resource) Create a resource model builder initialized by introspecting an annotated JAX-RS resource instance.
static Resource.Builder	builder(Resource resource) Get a new resource model builder initialized from a given resource model.
static Resource.Builder	builder(String path) Get a new resource model builder for a resource bound to a given path.
static Resource	from(Class<?> resourceClass) Create a resource model initialized by introspecting an annotated JAX-RS resource class.
static Resource	from(Object resource) Create a resource model initialized by introspecting an annotated JAX-RS resource instance.
List<? extends ResourceModelComponent>	getComponents() Should return all existing resource model sub-components.
Set<Class<?>>	getHandlerClasses() Get the method handler classes for the resource methods registered on the resource.
Set<Object>	getHandlerInstances() Get the method handler (singleton) instances for the resource methods registered on the resource.
String	getName() Get the resource name.
String	getPath() Get the path direct assigned to the component.
static Path	getPath(Class<?> resourceClass) Get the resource class @Path annotation.
PathPattern	getPathPattern() Get the path pattern that can be used for matching the remaining request URI against this component represented by this model.
List<ResourceMethod>	getResourceMethods() Provides a non-null list of resource methods available on the resource.
List<ResourceMethod>	getSubResourceLocators() Provides a non-null list of sub-resource locators available on the resource.
List<ResourceMethod>	getSubResourceMethods() Provides a non-null list of sub-resource methods available on the resource.
static boolean	isAcceptable(Class<?> c) Check if the class is acceptable as a JAX-RS provider or resource.
boolean	isRootResource() Check if this resource model models a JAX-RS root resource.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

builder

public static Resource.Builder builder()

Get a new unbound resource model builder.

Note that a resource built from the returned builder is NOT automatically marked to be a root resource. This can be changed by invoking the path(...) method on the returned builder.

Returns:

new unbound resource model builder.

See Also:

Resource.Builder.path(java.lang.String)

builder

public static Resource.Builder builder(String path)

Get a new resource model builder for a resource bound to a given path.

Note that a resource built from the returned builder is automatically marked to be a root resource.

Parameters:

path - resource path.

Returns:

new resource model builder.

See Also:

Resource.Builder.path(java.lang.String)

builder

public static Resource.Builder builder(Class<?> resourceClass)
                                throws IllegalArgumentException

Create a resource model builder initialized by introspecting an annotated JAX-RS resource class.

Method performs an acceptability check, on the resource class prior to the resource model creation.

Parameters:

resourceClass - resource class to be modelled.

Returns:

resource model builder initialized by the class or null if the class does not represent a resource.

Throws:

IllegalArgumentException - in case the class is not acceptable as a JAX-RS resource.

builder

public static Resource.Builder builder(Object resource)

Create a resource model builder initialized by introspecting an annotated JAX-RS resource instance.

Unlike builder(Class), this method does not perform the acceptability check, since it is assumed that the instance of the resource has already been created and is acceptable.

Parameters:

resource - resource instance to be modelled.

Returns:

resource model builder initialized by instance or null if the instance does not represent a resource.

from

public static Resource from(Class<?> resourceClass)
                     throws IllegalArgumentException

Create a resource model initialized by introspecting an annotated JAX-RS resource class.

Method performs an acceptability check, on the resource class prior to the resource model creation.

Parameters:

resourceClass - resource class to be modelled.

Returns:

resource model initialized by the class or null if the class does not represent a resource.

Throws:

IllegalArgumentException - in case the class is not acceptable as a JAX-RS resource.

from

public static Resource from(Object resource)

Create a resource model initialized by introspecting an annotated JAX-RS resource instance.

Unlike builder(Class), this method does not perform the acceptability check, since it is assumed that the instance of the resource has already been created and is acceptable.

Parameters:

resource - resource instance to be modelled.

Returns:

resource model initialized by instance or null if the instance does not represent a resource.

isAcceptable

public static boolean isAcceptable(Class<?> c)

Check if the class is acceptable as a JAX-RS provider or resource.

Method returns false if the class is either

• abstract
• interface
• annotation
• primitive
• local class
• non-static member class

Parameters:

c - class to be checked.

Returns:

true if the class is an acceptable JAX-RS provider or resource, false otherwise.

getPath

public static Path getPath(Class<?> resourceClass)

Get the resource class @Path annotation.

May return null in case there is no @Path annotation on the resource.

Parameters:

resourceClass - resource class.

Returns:

@Path annotation instance if present on the resource class (i.e. the class is a root resource class), or null otherwise.

builder

public static Resource.Builder builder(Resource resource)

Get a new resource model builder initialized from a given resource model.

Parameters:

resource - resource model initializing the resource builder.

Returns:

new resource model builder.

isRootResource

public boolean isRootResource()

Check if this resource model models a JAX-RS root resource.

Returns:

true, if this is a model of a JAX-RS root resource, false otherwise.

getPath

public String getPath()

Description copied from interface: Routed

Get the path direct assigned to the component.

Specified by:

getPath in interface Routed

Returns:

component path.

getPathPattern

public PathPattern getPathPattern()

Description copied from interface: Routed

Get the path pattern that can be used for matching the remaining request URI against this component represented by this model.

Specified by:

getPathPattern in interface Routed

Returns:

component path pattern.

getName

public String getName()

Get the resource name.

If the resource was constructed from a JAX-RS annotated resource class, the resource name will be set to the fully-qualified name of the resource class.

Returns:

reference JAX-RS resource handler class.

getResourceMethods

public List<ResourceMethod> getResourceMethods()

Provides a non-null list of resource methods available on the resource.

Returns:

non-null abstract resource method list.

getSubResourceMethods

public List<ResourceMethod> getSubResourceMethods()

Provides a non-null list of sub-resource methods available on the resource.

Returns:

non-null abstract sub-resource method list.

getSubResourceLocators

public List<ResourceMethod> getSubResourceLocators()

Provides a non-null list of sub-resource locators available on the resource.

Returns:

non-null abstract sub-resource locator list.

getHandlerClasses

public Set<Class<?>> getHandlerClasses()

Get the method handler classes for the resource methods registered on the resource.

Returns:

resource method handler classes.

getHandlerInstances

public Set<Object> getHandlerInstances()

Get the method handler (singleton) instances for the resource methods registered on the resource.

Returns:

resource method handler instances.

accept

public void accept(ResourceModelVisitor visitor)

Description copied from interface: ResourceModelComponent

A component should call the visitor back with an appropriate visitor interface method to give it a chance to process.

Specified by:

accept in interface ResourceModelComponent

Parameters:

visitor - resource model visitor.

toString

public String toString()

Overrides:

toString in class Object

getComponents

public List<? extends ResourceModelComponent> getComponents()

Description copied from interface: ResourceModelComponent

Should return all existing resource model sub-components.

Specified by:

getComponents in interface ResourceModelComponent

Returns:

list of all sub-components