이 콘텐츠는 선택한 언어로 제공되지 않습니다.

3.2. Using JAX-RS APIs

The standard JAX-RS API specifies annotations that can be used to inject values into fields, bean properties, and method parameters. The annotations can be split up into three distinct types:

3.2.1. Injecting data from a request URI
링크 복사

Overview
링크 복사

One of the best practices for designing a RESTful Web service is that each resource should have a unique URI. A developer can use this principle to provide a good deal of information to the underlying resource implementation. When designing URI templates for a resource, a developer can build the templates to include parameter information that can be injected into the resource implementation. Developers can also leverage query and matrix parameters for feeding information into the resource implementations.

Getting data from the URI's path
링크 복사

One of the more common mechanisms for getting information about a resource is through the variables used in creating the URI templates for a resource. This is accomplished using the javax.ws.rs.PathParam annotation. The @PathParam annotation has a single parameter that identifies the URI template variable from which the data will be injected.

In Example 3.1, “Injecting data from a URI template variable” the @PathParam annotation specifies that the value of the URI template variable color is injected into the itemColor field.

Example 3.1. Injecting data from a URI template variable

import javax.ws.rs.Path;
import javax.ws.rs.PathParam
...

@Path("/boxes/{shape}/{color}")
class Box
{
  ...

  @PathParam("color")
  String itemColor;

  ...
}

import javax.ws.rs.Path;
import javax.ws.rs.PathParam
...

@Path("/boxes/{shape}/{color}")
class Box
{
  ...

  @PathParam("color")
  String itemColor;

  ...
}

Copy to Clipboard

Toggle word wrap

The data types supported by the @PathParam annotation are different from the ones described in the section called “Supported data types”. The entity into which the @PathParam annotation injects data must be of one of the following types:

PathSegment
The value will be the final segment of the matching part of the path.
List<PathSegment>
The value will be a list of PathSegment objects corresponding to the path segment(s) that matched the named template parameter.
primitives such as int, char, or long
Objects that have a constructor that accepts a single String argument
Objects that have a static valueOf() method that accepts a single String argument

Using query parameters
링크 복사

A common way of passing information on the Web is to use query parameters in a URI. Query parameters appear at the end of the URI and are separated from the resource location portion of the URI by a question mark(?). They consist of one, or more, name value pairs where the name and value are separated by an equal sign(=). When more than one query parameter is specified, the pairs are separated from each other by either a semicolon(;) or an ampersand(&). Example 3.2, “URI with a query string” shows the syntax of a URI with query parameters.

Example 3.2. URI with a query string

http://fusesource.org?name=value;name2=value2;...

http://fusesource.org?name=value;name2=value2;...

Copy to Clipboard

Toggle word wrap

Note

You can use either the semicolon or the ampersand to separate query parameters, but not both.

The javax.ws.rs.QueryParam annotation extracts the value of a query parameter and injects it into a JAX-RS resource. The annotation takes a single parameter that identifies the name of the query parameter from which the value is extracted and injected into the specified field, bean property, or parameter. The @QueryParam annotation supports the types described in the section called “Supported data types”.

Example 3.3, “Resource method using data from a query parameter” shows a resource method that injects the value of the query parameter id into the method's id parameter.

Example 3.3. Resource method using data from a query parameter

import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  @Path("\{type}")
  public void updateMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }
  ...
}

import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  @Path("\{type}")
  public void updateMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }
  ...
}

Copy to Clipboard

Toggle word wrap

To process an HTTP POST to /monstersforhire/daikaiju?id=jonas the updateMonster() method's type is set to daikaiju and the id is set to jonas.

Using matrix parameters
링크 복사

URI matrix parameters, like URI query parameters, are name/value pairs that can provide additional information selecting a resource. Unlike query parameters, matrix parameters can appear anywhere in a URI and they are separated from the hierarchical path segments of the URI using a semicolon(;). /mostersforhire/daikaiju;id=jonas has one matrix parameter called id and /monstersforhire/japan;type=daikaiju/flying;wingspan=40 has two matrix parameters called type and wingspan.

Note

Matrix parameters are not evaluated when computing a resource's URI. So, the URI used to locate the proper resource to handle the request URI /monstersforhire/japan;type=daikaiju/flying;wingspan=40 is /monstersforhire/japan/flying.

The value of a matrix parameter is injected into a field, parameter, or bean property using the javax.ws.rs.MatrixParam annotation. The annotation takes a single parameter that identifies the name of the matrix parameter from which the value is extracted and injected into the specified field, bean property, or parameter. The @MatrixParam annotation supports the types described in the section called “Supported data types”.

Example 3.4, “Resource method using data from matrix parameters” shows a resource method that injects the value of the matrix parameters type and id into the method's parameters.

Example 3.4. Resource method using data from matrix parameters

import javax.ws.rs.MatrixParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  public void updateMonster(@MatrixParam("type") String type,
                            @MatrixParam("id") String id)
  {
    ...
  }
  ...
}

import javax.ws.rs.MatrixParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  public void updateMonster(@MatrixParam("type") String type,
                            @MatrixParam("id") String id)
  {
    ...
  }
  ...
}

Copy to Clipboard

Toggle word wrap

To process an HTTP POST to /monstersforhire;type=daikaiju;id=whale the updateMonster() method's type is set to daikaiju and the id is set to whale.

Note

JAX-RS evaluates all of the matrix parameters in a URI at once, so it cannot enforce constraints on a matrix parameters location in a URI. For example /monstersforhire/japan;type=daikaiju/flying;wingspan=40 , /monstersforhire/japan/flying;type=daikaiju;wingspan=40, and /monstersforhire/japan;type=daikaiju;wingspan=40/flying are all treated as equivalent by a RESTful Web service implemented using the JAX-RS APIs.

Disabling URI decoding
링크 복사

By default all request URIs are decoded. So the URI /monster/night%20stalker and the URI /monster/night stalker are equivalent. The automatic URI decoding makes it easy to send characters outside of the ASCII character set as parameters.

If you do not wish to have URI automatically decoded, you can use the javax.ws.rs.Encoded annotation to deactivate the URI decoding. The annotation can be used to deactivate URI decoding at the following levels:

class level—Decorating a class with the @Encoded annotation deactivates the URI decoding for all parameters, field, and bean properties in the class.
method level—Decorating a method with the @Encoded annotation deactivates the URI decoding for all parameters of the class.
parameter/field level—Decorating a parameter or field with the @Encoded annotation deactivates the URI decoding for all parameters of the class.

Example 3.5, “Disabling URI decoding” shows a resource whose getMonster() method does not use URI decoding. The addMonster() method only disables URI decoding for the type parameter.

Example 3.5. Disabling URI decoding

@Path("/monstersforhire/")
public class MonsterService
{
  ...

  @GET
  @Encoded
  @Path("\{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }

  @PUT
  @Path("\{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @QueryParam("id") String id)
  {
    ...
  }
  ...
}

@Path("/monstersforhire/")
public class MonsterService
{
  ...

  @GET
  @Encoded
  @Path("\{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }

  @PUT
  @Path("\{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @QueryParam("id") String id)
  {
    ...
  }
  ...
}

Copy to Clipboard

Toggle word wrap

Error handling
링크 복사

If an error occurs when attempting to inject data using one of the URI injection annotations a WebApplicationException exception wraps the original exception is generated. The WebApplicationException exception's status is set to 404.

3.2.2. Injecting data from the HTTP message header
링크 복사

Overview
링크 복사

In normal usage the HTTP headers in a request message pass along generic information about the message, how it is to be handled in transit, and details about the expected response. While a few standard headers are commonly recognized and used, the HTTP specification allows for any name/value pair to be used as an HTTP header. The JAX-RS APIs provide an easy mechanism for injecting HTTP header information into a resource implementation.

One of the most commonly used HTTP headers is the cookie. Cookies allow HTTP clients and servers to share static information across multiple request/response sequences. The JAX-RS APIs provide an annotation inject data directly from a cookie into a resource implementation.

Injecting information from the HTTP headers
링크 복사

The javax.ws.rs.HeaderParam annotation is used to inject the data from an HTTP header field into a parameter, field, or bean property. It has a single parameter that specifies the name of the HTTP header field from which the value is extracted and injected into the resource implementation. The associated parameter, field, or bean property must conform to the data types described in the section called “Supported data types”.

Example 3.6, “Injecting the If-Modified-Since header” shows code for injecting the value of the HTTP If-Modified-Since header into a class' oldestDate field.

Example 3.6. Injecting the If-Modified-Since header

import javax.ws.rs.HeaderParam;
...
class RecordKeeper
{
  ...
  @HeaderParam("If-Modified-Since")
  String oldestDate;
  ...
}

import javax.ws.rs.HeaderParam;
...
class RecordKeeper
{
  ...
  @HeaderParam("If-Modified-Since")
  String oldestDate;
  ...
}

Copy to Clipboard

Toggle word wrap

Injecting information from a cookie
링크 복사

Cookies are a special type of HTTP header. They are made up of one or more name/value pairs that are passed to the resource implementation on the first request. After the first request, the cookie is passes back and forth between the provider and consumer with each message. Only the consumer, because they generate requests, can change the cookie. Cookies are commonly used to maintain session across multiple request/response sequences, storing user settings, and other data that can persist.

The javax.ws.rs.CookieParam annotation extracts the value from a cookie's field and injects it into a resource implementation. It takes a single parameter that specifies the name of the cookie's field from which the value is to be extracted. In addition to the data types listed in the section called “Supported data types”, entities decorated with the @CookieParam can also be a Cookie object.

Example 3.7, “Injecting a cookie” shows code for injecting the value of the handle cookie into a field in the CB class.

Example 3.7. Injecting a cookie

import javax.ws.rs.CookieParam;
...
class CB
{
  ...
  @CookieParam("handle")
  String handle;
  ...
}

import javax.ws.rs.CookieParam;
...
class CB
{
  ...
  @CookieParam("handle")
  String handle;
  ...
}

Copy to Clipboard

Toggle word wrap

Error handling
링크 복사

If an error occurs when attempting to inject data using one of the HTTP message injection annotations a WebApplicationException exception wrapping the original exception is generated. The WebApplicationException exception's status is set to 400.

3.2.3. Injecting data from HTML forms
링크 복사

Overview
링크 복사

HTML forms are an easy means of getting information from a user and they are also easy to create. Form data can be used for HTTP GET requests and HTTP POST requests:

GET: When form data is sent as part of an HTTP GET request the data is appended to the URI as a set of query parameters. Injecting data from query parameters is discussed in the section called “Using query parameters”.
POST: When form data is sent as part of an HTTP POST request the data is placed in the HTTP message body. The form data can be handled using a regular entity parameter that supports the form data. It can also be handled by using the @FormParam annotation to extract the data and inject the pieces into resource method parameters.

Using the @FormParam annotation to inject form data
링크 복사

The javax.ws.rs.FormParam annotation extracts field values from form data and injects the value into resource method parameters. The annotation takes a single parameter that specifies the key of the field from which it extracts the values. The associated parameter must conform to the data types described in the section called “Supported data types”.

Important

The JAX-RS API Javadoc states that the @FormParam annotation can be placed on fields, methods, and parameters. However, the @FormParam annotation is only meaningful when placed on resource method parameters.

Example
링크 복사

Example 3.8, “Injecting form data into resource method parameters” shows a resource method that injects form data into its parameters. The method assumes that the client's form includes three fields—title, tags, and body—that contain string data.

Example 3.8. Injecting form data into resource method parameters

import javax.ws.rs.FormParam;
import javax.ws.rs.POST;

...
@POST
public boolean updatePost(@FormParam("title") String title,
                          @FormParam("tags") String tags,
                          @FormParam("body") String post)
{
  ...
}

import javax.ws.rs.FormParam;
import javax.ws.rs.POST;

...
@POST
public boolean updatePost(@FormParam("title") String title,
                          @FormParam("tags") String tags,
                          @FormParam("body") String post)
{
  ...
}

Copy to Clipboard

Toggle word wrap

3.2.4. Specifying a default value to inject
링크 복사

Overview
링크 복사

To provide for a more robust service implementation, you may want to ensure that any optional parameters can be set to a default value. This can be particularly useful for values that are taken from query parameters and matrix parameters since entering long URI strings is highly error prone. You may also want to set a default value for a parameter extracted from a cookie since it is possible for a requesting system not have the proper information to construct a cookie with all the values.

The javax.ws.rs.DefaultValue annotation can be used in conjunction with the following injection annotations:

@PathParam
@QueryParam
@MatrixParam
@FormParam
@HeaderParam
@CookieParam

The @DefaultValue annotation specifies a default value to be used when the data corresponding to the injection annotation is not present in the request.

Syntax
링크 복사

Example 3.9, “Syntax for setting the default value of a parameter” shows the syntax for using the @DefaultValue annotation.

Example 3.9. Syntax for setting the default value of a parameter

import javax.ws.rs.DefaultValue;
  ...
  void resourceMethod(@MatrixParam("matrix")
                      @DefaultValue("value)
                      int someValue, ... )
  ...

import javax.ws.rs.DefaultValue;
  ...
  void resourceMethod(@MatrixParam("matrix")
                      @DefaultValue("value)
                      int someValue, ... )
  ...

Copy to Clipboard

Toggle word wrap

The annotation must come before the parameter, bean, or field, it will effect. The position of the @DefaultValue annotation relative to the accompanying injection annotation does not matter.

The @DefaultValue annotation takes a single parameter. This parameter is the value that will be injected into the field if the proper data cannot be extracted based on the injection annotation. The value can be any String value. The value should be compatible with type of the associated field. For example, if the associated field is of type int, a default value of blue results in an exception.

Dealing with lists and sets
링크 복사

If the type of the annotated parameter, bean or field is List, Set, or SortedSet then the resulting collection will have a single entry mapped from the supplied default value.

Example
링크 복사

Example 3.10, “Setting default values” shows two examples of using the @DefaultValue to specify a default value for a field whose value is injected.

Example 3.10. Setting default values

import javax.ws.rs.DefaultValue;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/monster")
public class MonsterService
{

  @Get
  public Monster getMonster(@QueryParam("id") @DefaultValue("42") int id,
                            @QueryParam("type") @DefaultValue("bogeyman") String type)
  {
    ...
  }

  ...
}

import javax.ws.rs.DefaultValue;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/monster")
public class MonsterService
{

  @Get
  public Monster getMonster(@QueryParam("id") @DefaultValue("42") int id,
                            @QueryParam("type") @DefaultValue("bogeyman") String type)
  {
    ...
  }

  ...
}

Copy to Clipboard

Toggle word wrap

The getMonster() method in Example 3.10, “Setting default values” is invoked when a GET request is sent to baseURI/monster. The method expects two query parameters, id and type, appended to the URI. So a GET request using the URI baseURI/monster?id=1&type=fomóiri would return the Fomóiri with the id of one.

Because the @DefaultValue annotation is placed on both parameters, the getMonster() method can function if the query parameters are omitted. A GET request sent to baseURI/monster is equivalent to a GET request using the URI baseURI/monster?id=42&type=bogeyman.

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

3.2. Using JAX-RS APIs

3.2.1. Injecting data from a request URI
링크 복사

Overview
링크 복사

Getting data from the URI's path
링크 복사

Using query parameters
링크 복사

Using matrix parameters
링크 복사

Disabling URI decoding
링크 복사

Error handling
링크 복사

3.2.2. Injecting data from the HTTP message header
링크 복사

Overview
링크 복사

Injecting information from the HTTP headers
링크 복사

Injecting information from a cookie
링크 복사

Error handling
링크 복사

3.2.3. Injecting data from HTML forms
링크 복사

Overview
링크 복사

Using the @FormParam annotation to inject form data
링크 복사

Example
링크 복사

3.2.4. Specifying a default value to inject
링크 복사

Overview
링크 복사

Syntax
링크 복사

Dealing with lists and sets
링크 복사

Example
링크 복사

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

3.2. Using JAX-RS APIs

3.2.1. Injecting data from a request URI링크 복사링크가 클립보드에 복사되었습니다!

Overview링크 복사링크가 클립보드에 복사되었습니다!

Getting data from the URI's path링크 복사링크가 클립보드에 복사되었습니다!

Using query parameters링크 복사링크가 클립보드에 복사되었습니다!

Using matrix parameters링크 복사링크가 클립보드에 복사되었습니다!

Disabling URI decoding링크 복사링크가 클립보드에 복사되었습니다!

Error handling링크 복사링크가 클립보드에 복사되었습니다!

3.2.2. Injecting data from the HTTP message header링크 복사링크가 클립보드에 복사되었습니다!

Overview링크 복사링크가 클립보드에 복사되었습니다!

Injecting information from the HTTP headers링크 복사링크가 클립보드에 복사되었습니다!

Injecting information from a cookie링크 복사링크가 클립보드에 복사되었습니다!

Error handling링크 복사링크가 클립보드에 복사되었습니다!

3.2.3. Injecting data from HTML forms링크 복사링크가 클립보드에 복사되었습니다!

Overview링크 복사링크가 클립보드에 복사되었습니다!

Using the @FormParam annotation to inject form data링크 복사링크가 클립보드에 복사되었습니다!

Example링크 복사링크가 클립보드에 복사되었습니다!

3.2.4. Specifying a default value to inject링크 복사링크가 클립보드에 복사되었습니다!

Overview링크 복사링크가 클립보드에 복사되었습니다!

Syntax링크 복사링크가 클립보드에 복사되었습니다!

Dealing with lists and sets링크 복사링크가 클립보드에 복사되었습니다!

Example링크 복사링크가 클립보드에 복사되었습니다!

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat 소개

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

3.2.1. Injecting data from a request URI
링크 복사

Overview
링크 복사

Getting data from the URI's path
링크 복사

Using query parameters
링크 복사

Using matrix parameters
링크 복사

Disabling URI decoding
링크 복사

Error handling
링크 복사

3.2.2. Injecting data from the HTTP message header
링크 복사

Overview
링크 복사

Injecting information from the HTTP headers
링크 복사

Injecting information from a cookie
링크 복사

Error handling
링크 복사

3.2.3. Injecting data from HTML forms
링크 복사

Overview
링크 복사

Using the @FormParam annotation to inject form data
링크 복사

Example
링크 복사

3.2.4. Specifying a default value to inject
링크 복사

Overview
링크 복사

Syntax
링크 복사

Dealing with lists and sets
링크 복사

Example
링크 복사