Java Platform, Enterprise Edition (Java EE) 8 The Java EE Tutorial

## Annotations for Field and Bean Properties of Resource Classes

JAX-RS annotations for resource classes let you extract specific parts or values from a Uniform Resource Identifier (URI) or request header.

JAX-RS provides the annotations listed in Table 32-1.

Table 32-1 Advanced JAX-RS Annotations

Annotation | Description
`@Context` | Injects information into a class field, bean property, or method parameter
`@CookieParam` | Extracts information from cookies declared in the cookie request header
`@FormParam` | Extracts information from a request representation whose content type is `application/x-www-form-urlencoded`
`@HeaderParam` | Extracts the value of a header
`@MatrixParam` | Extracts the value of a URI matrix parameter
`@PathParam` | Extracts the value of a URI template parameter
`@QueryParam` | Extracts the value of a URI query parameter

### Extracting Path Parameters

URI path templates are URIs with variables embedded within the URI syntax. The `@PathParam` annotation lets you use variable URI path fragments when you call a method.

The following code snippet shows how to extract the last name of an employee when the employee’s email address is provided:

    @Path("/employees/{firstname}.{lastname}@{domain}.com")
    public class EmpResource {

        @GET
        @Produces("text/xml")
        public String getEmployeelastname(@PathParam("lastname") String lastName) {
          ...
        }
    }

In this example, the `@Path` annotation defines the URI variables (or path parameters) `{firstname}`, `{lastname}`, and `{domain}`. The `@PathParam` in the method parameter of the request method extracts the last name from the email address.

If your HTTP request is `GET` `/employees/john.doe@example.com`, the value “doe” is injected into `{lastname}`.

You can specify several path parameters in one URI.

You can declare a regular expression with a URI variable. For example, if it is required that the last name must consist only of lowercase and uppercase characters, you can declare the following regular expression:

    @Path("/employees/{firstname}.{lastname[a-zA-Z]*}@{domain}.com")

If the last name does not match the regular expression, a 404 response is returned.

### Extracting Query Parameters

Use the `@QueryParam` annotation to extract query parameters from the query component of the request URI.

For instance, to query all employees who have joined within a specific range of years, use a method signature like the following:

    @Path("/employees/")
    @GET
    public Response getEmployees(
            @DefaultValue("2003") @QueryParam("minyear") int minyear,
            @DefaultValue("2013") @QueryParam("maxyear") int maxyear)
        {...}

This code snippet defines two query parameters, `minyear` and `maxyear`. The following HTTP request would query for all employees who have joined between 2003 and 2013:

    GET /employees?maxyear=2013&minyear=2003

The `@DefaultValue` annotation defines a default value, which is to be used if no values are provided for the query parameters. By default, JAX-RS assigns a null value for `Object` values and zero for primitive data types. You can use the `@DefaultValue` annotation to eliminate null or zero values and define your own default values for a parameter.

### Extracting Form Data

Use the `@FormParam` annotation to extract form parameters from HTML forms. For example, the following form accepts the name, address, and manager’s name of an employee:

    <FORM action="http://example.com/employees/" method="post">
      <p>
        <fieldset>
          Employee name: <INPUT type="text" name="empname" tabindex="1">
          Employee address: <INPUT type="text" name="empaddress" tabindex="2">
          Manager name: <INPUT type="text" name="managername" tabindex="3">
        </fieldset>
      </p>
    </FORM>

Use the following code snippet to extract the manager name from this HTML form:

    @POST
    @Consumes("application/x-www-form-urlencoded")
    public void post(@FormParam("managername") String managername) {
        // Store the value
        ...
    }

To obtain a map of form parameter names to values, use a code snippet like the following:

    @POST
    @Consumes("application/x-www-form-urlencoded")
    public void post(MultivaluedMap<String, String> formParams) {
        // Store the message
    }

### Extracting the Java Type of a Request or Response

The `javax.ws.rs.core.Context` annotation retrieves the Java types related to a request or response.

The `javax.ws.rs.core.UriInfo` interface provides information about the components of a request URI. The following code snippet shows how to obtain a map of query and path parameter names to values:

    @GET
    public String getParams(@Context UriInfo ui) {
        MultivaluedMap<String, String> queryParams = ui.getQueryParameters();
        MultivaluedMap<String, String> pathParams = ui.getPathParameters();
    }

The `javax.ws.rs.core.HttpHeaders` interface provides information about request headers and cookies. The following code snippet shows how to obtain a map of header and cookie parameter names to values:

    @GET
    public String getHeaders(@Context HttpHeaders hh) {
        MultivaluedMap<String, String> headerParams = hh.getRequestHeaders();
        MultivaluedMap<String, Cookie> pathParams = hh.getCookies();
    }

Copyright © 2017, Oracle and/or its affiliates. All rights reserved.