Resource Methods

Resource methods

Resource methods

Resource methods are methods of a resource class annotated with request method designation. Method which has such annotations musr be public. JAX-RS defines a next set of request methods: @GET, @POST, @PUT, @DELETE, @HEAD. This set can be extended by writing own annotations and that annotation must be annotated with @HttpMethod annotation. Here is example of creation annotation for WebDav method PROPFIND:

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import javax.ws.rs.HttpMethod;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("PROPFIND")
public @interface PROPFIND {
}

See also about X-HTTP-Method-Override HTTP header.

Parameters

Parametrs of resources method may containes one of annotation described bellow. Method also may have exactly one not annotated parameter, called entity parameter.

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
@javax.ws.rs.FormParam	HTML form parameters
@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 or HTML form decoding) of parameter values bound using @QueryParam, @PathParam, @FormParam, @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	Provide access to security related information, such as user principal information and checking user's roles. Some information may be not available if user was not authenticated.
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.

Entity parameter

Entity parameter is produced from request body. Note: There is one limitation about entity parameter type: if at least one parameter is annotated with @javax.ws.rs.FormParam then entity parameter MAY NOT have other type then MutivaluedMap<String, String>. See list of supported entity parameters in Message Body Providers section.

Return type

Methods may return one of the following types:

Java type	Response status and description
void	Response with status 204 end empty body.
javax.ws.rs.core.Response	Response with body specified in entity variable, status specified in status variable and set of specified headers.
javax.ws.rs.core.GenericEntity<T>	Entity of response of generic type. Need this if method return generic type. If return value is not null, a 200 status returned, null value returns 204 status.
java.lang.Object	Other types. If return value is not null, a 200 status returned, null value returns 204 status.

Supported objects and content types are the same as Entity parameter except multipart/** content type. This type is not supported for output. And one more java type javax.ws.rs.core.StreamingOutput is supported for output. This type should be in use when service need to stream the output. It should be very useful for large responses.

@Consumes and @Produces

@Consumes annotation declare which content type is acceptable for method. If method does not have such annotation then resource class will be checked for this annotation. It minds annotation may be provided once at resource class and will be actual for all methods of this resource class. If annotation nor presents at method nor presents on resource class method will be considered as consuming any types of content.

@Produces annotations declare that content type which method produced. Annotations from resource class contained current method is processed in the same way as for @Consumes annotation.

@GET
@Produces("application/json")
public Book get()
{
...
}

@PUT
@Consumes("application/json")
public void put()
{
...
}

@Path

Resource methods may be annotated with @Path annotation. Such methods called sub-resources. In this case to get this method invoked request path must be matched to URI template created by concatenating the URI template of resource class and resource method.