43.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:
- It must be public.
- It must be decorated with one of the HTTP method annotations described in the section called “Specifying HTTP verbs”.
- It must not have more than one entity parameter as described in the section called “Parameters”.
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.ImportantA resource method can have only one entity parameter.For more information on entity providers see Chapter 48, 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 44, Passing Information into Resource Classes and Methods.
Example 43.4, “Resource method with a valid parameter list” shows a resource method with a valid parameter list.
Example 43.4. Resource method with a valid parameter list
@POST
@Path("disaster/monster/giant/{id}")
public void addDaikaiju(Kaiju kaiju,
@PathParam("id") String id)
{
...
}
Example 43.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 43.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:
void- any Java class for which the application has an entity providerFor more information on entity providers see Chapter 48, Entity Support.
- a
ResponseobjectFor more information onResponseobjects see Section 45.3, “Fine tuning an application's responses”. - a
GenericEntity<T>objectFor more information onGenericEntity<T>objects see Section 45.4, “Returning entities with generic type information”.
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.
