Resources

JAX-RS resources

Resources

Resource is a Java class that uses JAX-RS annotations which describe it as corresponded Web-Resource. Resource must have at least one method with @javax.ws.rs.Path annotation or request method annotation (GET, POST,etc). There is two kind of resources root resources and not root resources. In other hand resources may be singleton and per-request. Instance of per-request resources created for each request, instances of singleton resources exists allways. Per-request behavior is declared by specification as default for all resources. Since per-request instanced created for each request this way look preferable for concurrency.

Root resources. All root resources must be annotated with @javax.ws.rs.Path. Root resources provide access to sub-resources. Root resource classes are instantiated by the EverRest in runtime.

• Constructor. Root resource must have at least one public constructor. Constructor may have parameters, value for this parameters should be provided by EverRest in runtime. If class has more than one public constructor then the constructor with the most parameters will be used. Parameters may be annotated with one of the following: @Context, @Header-Param, @CookieParam, @MatrixParam, @QueryParam, @PathParam or @org.everrest.core.Property. Such parameters have no sence for root resources that has singleton lifecycle. Constructor's parameters without annotation will be resolved by org.everrest.core.DependencySupplier. See Dependency Resolving for details.
• Fields. Fields of per-request resource may be annotated with the same set of annotation as constructor's parameters plus @org.everrest.core.Inject. Since fields injected in runtime such annotation have not sence for resources with lifecycle other then per-request. Filds annotated with @org.everrest.core.Inject will be resolved by DependencySupplier. See Dependency Resolving for details.
• Singleton. Note: There is no any requirements about constructors and fields of singleton resources. Developer of resources is responsible about creation instance of resource.
• Deploy Root resources may be deployed in EverRest framework in two ways:

1. Use javax.ws.rs.core.Application. This is abstract class which can deliver instances or classes of resources. Method getClasses() delivers per-request resources, method getSingletons() devivers singleton resources.

EverrestProcessor processor = new EverrestProcessor(new ResourceBinderImpl(),
   new ApplicationProviderBinder(),
   new DependencySupplierImpl(),
   new EverrestConfiguration(),
   new Application() {
      @Override
      public Set<Class<?>> getClasses() {
         Set<Class<?>> cls = new HashSet<Class<?>>(1);
         cls.add(MyResource.class);
         return cls;
      }
   });
// processor is ready to process request to your resource(s).

2. Under servlet container is possible to scan all classes in you web application to find classes annotated with JAX-RS annotation. See Servlets Integration for details.

Constructor parameters and fields.

Allowed annotations:

Annotation type	Description
@javax.ws.rs.Context	Inject instances of JAX-RS or request components. See details about this annotation bellow.
@javax.ws.rs.HeaderParam	Inject the value of header parameter with specified name, e.g. @HeaderParam("Content-type")
@javax.ws.rs.CookieParam	Inject the value extracted from HTTP cookie.
@javax.ws.rs.MatrixParam	Inject the value extracted from URI matrix parameter.
@javax.ws.rs.QueryParam	Inject the value extracted from query parameter
@javax.ws.rs.PathParam	Inject the value extracted from request URI.
@org.everrest.core.Property	Inject the value of named property from org.everrest.core.InitialProperties
@javax.ws.rs.DefaultValue	Provide String representation of default value for parameter of field. Will be used if there is not info for initialization parameter in request. Used together with any annotation described above (except @Context)
@javax.ws.rs.Encoded	Disable automatic decoding (URL decoding) of parameter values bound using @QueryParam, @PathParam, @MatrixParam.

Allowed types for annotated parameters are (except @javax.ws.rs.Context):

1. Primitive types, except char.
2. java.lang.String
3. Types that have constructor with single parameter java.lang.String
4. Types that have static method valueOf with single parameter java.lang.String
5. List<T>, Set<T>, or SortedSet<T>, where T satisfies 2, 3 or 4 above

Fields and parameters with @javax.ws.rs.Context annotation:

Type	Description
javax.ws.rs.core.HttpHeaders	Provide access to all HTTP headers information
javax.ws.rs.core.SecurityContext
javax.ws.rs.core.Request	JAX-RS request
javax.ws.rs.core.UriInfo	URI related information
javax.ws.rs.ext.Providers	Providers
org.everrest.core.InitialProperties	Provide access to context properties. See static methods get/setProperty in org.everrest.core.impl.RequestHandlerImpl
javax.servlet.http.HttpServletRequest	Servlet request
javax.servlet.http.HttpServletResponse	Servlet response
javax.servlet.ServletConfig	Servlet config
javax.servlet.ServletContext	Servlet context

Example:

@Path("a")
public class MyResource
{
   @Context
   private HttpHeaders headers;

   @QueryParam("name")
   private String name;

   public MyResource(@Context HttpServletRequest request)
   {
   }

   @GET
   public String get()
   {
      return name;
   }
}

None-Root resources.

Such resources are instantiated in runtime by JAX-RS application and not need to have public constructor.