45.4. Working with resource methods

Overview

Resource methods are annotated using JAX-RS annotations. They have one of the HTTP method annotation specifying the types of requests that the method processes. JAX-RS places several constraints on resource methods.

General constraints

All resource methods must meet the following conditions:

Parameters

Resource method parameters take two forms:
  • entity parameters—Entity parameters are not annotated. Their value is mapped from the request entity body. An entity parameter can be of any type for which your application has an entity provider. Typically they are JAXB objects.
    Important
    A resource method can have only one entity parameter.
    For more information on entity providers see Chapter 49, Entity Support.
  • annotated parameters—Annotated parameters use one of the JAX-RS annotations that specify how the value of the parameter is mapped from the request. Typically, the value of the parameter is mapped from portions of the request URI.
    For more information about using the JAX-RS annotations for mapping request data to method parameters see Chapter 46, Passing Information into Resource Classes and Methods.
Example 45.4, “Resource method with a valid parameter list” shows a resource method with a valid parameter list.

Example 45.4. Resource method with a valid parameter list

@POST
@Path("disaster/monster/giant/{id}")
public void addDaikaiju(Kaiju kaiju,
                        @PathParam("id") String id)
{
  ...
}
Example 45.5, “Resource method with an invalid parameter list” shows a resource method with an invalid parameter list. It has two parameters that are not annotated.

Example 45.5. Resource method with an invalid parameter list

@POST
@Path("disaster/monster/giant/")
public void addDaikaiju(Kaiju kaiju,
                        String id)
{
  ...
}

Return values

Resource methods can return one of the following:
All resource methods return an HTTP status code to the requester. When the return type of the method is void or the value being returned is null, the resource method sets the HTTP status code to 204. When the resource method returns any value other than null, it sets the HTTP status code to 200.