1. Developing and Securing RESTful Web Services for Oracle WebLogic Server
  2. Developing RESTful Web Services

2 Developing RESTful Web Services

To develop Jakarta Enterprise web services that conform to the Representational State Transfer (REST) architectural style using Jakarta RESTful Web Services (JAX-RS), you perform tasks such as defining the root resource class, mapping incoming HTTP requests to Java methods, customizing media types for requests and responses, and more.

  • About RESTful Web Service Development
    JAX-RS is a Java programming language API that uses annotations to simplify the development of RESTful web services. JAX-RS annotations are runtime annotations.
  • Defining the Root Resource Class
    A root resource class is a Plain Old Java Object (POJO) that meets specific annotation requirements.
  • Defining the Relative URI of the Root Resource and Subresources
    Add the javax.ws.rs.Path annotation at the class level of the resource to define the relative URI of the RESTful web service. Such classes are referred to as root resource classes.
  • Mapping Incoming HTTP Requests to Java Methods
    JAX-RS uses Jakarta annotations to map an incoming HTTP request to a Java method.
  • Customizing Media Types for the Request and Response Messages
    To customize the media types for request and response messages, add the javax.ws.rs.Consumes or javax.ws.rs.Produces annotation at the class level of the resource.
  • Extracting Information From the Request Message
    The javax.ws.rs package defines a set of annotations that enable you extract information from the request message to inject into parameters of your Java method.
  • Building Custom Response Messages
    Instead of the default response codes, you can customize the response codes returned or include additional metadata information in the response.
  • Mapping HTTP Request and Response Entity Bodies Using Entity Providers
    HTTP request and response entity bodies automatically support a set of Java types that can be utilized by your RESTful web service.
  • Accessing the Application Context
    The javax.ws.rs.core.Context annotation enables you to access information about the application deployment context and the context of individual requests.
  • Building URIs
    You can use javax.ws.rs.core.UriInfo to access application and request URI information.
  • Using Conditional GETs
    A conditional GET enables you to evaluate one or more preconditions before processing a GET request. If the preconditions are met, a Not Modified (304) response can be returned rather than the normal response, potentially reducing bandwidth and improving server performance.
  • Accessing the WADL
    The Web Application Description Language (WADL) is an XML-based file format that describes your RESTful web services application. By default, a basic WADL is generated at runtime and can be accessed from your RESTful web service by issuing a GET on the /application.wadl resource at the base URI of your RESTful application.
  • More Advanced RESTful Web Service Tasks
    The Jersey 2.29 User Guide provides information about more advanced RESTful web service development tasks.

About RESTful Web Service Development

JAX-RS is a Java programming language API that uses annotations to simplify the development of RESTful web services. JAX-RS annotations are runtime annotations. When you deploy the Jakarta EE application archive containing JAX-RS resource classes to WebLogic Server, as described in Building, Packaging, and Deploying RESTful Web Service Applications, the runtime configures the resources, generates the helper classes and artifacts, and exposes the resource to clients.

For information about developing RESTful web services using Oracle JDeveloper, see Creating RESTful Web Services and Clients in Developing Applications with Oracle JDeveloper.

The following sections provide more information about RESTful web service development:

Parent topic: Developing RESTful Web Services

Summary of Tasks to Develop RESTful Web Services

Table 2-1 summarizes a subset of the tasks that are required to develop RESTful web service using JAX-RS annotations. For more information about advanced tasks, see More Advanced RESTful Web Service Tasks.

Note:

In addition to the development tasks described in Table 2-1, you may wish to take advantage of features available with Jersey 2.x (JAX-RS 2.0 RI) when developing your RESTful web services. For a list of key features, see Table 1-2.

Table 2-1 Summary of Tasks to Develop RESTful Web Services

Task More Information

Define the root resource class.

Defining the Root Resource Class

Define the relative URI of the root resource class and its methods using the @Path annotation.

If you define the @Path annotation using a variable, you can assign a value to it using the @PathParam annotation.

Defining the Relative URI of the Root Resource and Subresources

Map incoming HTTP requests to your Java methods using @GET, @POST, @PUT, or @DELETE, to get, create, update, or delete representations of the resource, respectively.

Mapping Incoming HTTP Requests to Java Methods

Customize the request and response messages, as required, to specify the MIME media types of representations a resource can produce and consume.

Customizing Media Types for the Request and Response Messages

Extract information from the request.

Extracting Information From the Request Message

Build custom response messages to customize response codes or include additional metadata.

Building Custom Response Messages

Access information about the application deployment context or the context of individual requests.

Accessing the Application Context

Build new or extend existing resource URIs.

Building URIs

Evaluate one or more preconditions before processing a GET request, potentially reducing bandwidth and improving server performance.

Using Conditional GETs

Access the WADL.

Accessing the WADL

Optionally, create a class that extends javax.ws.rs.core.Application to define the components of a RESTful web service application deployment and provides additional metadata.

Packaging With an Application Subclass

Secure your RESTful web services.

Securing RESTful Web Services and Clients

Parent topic: About RESTful Web Service Development

Example of a RESTful Web Service

Example 2-1 provides a simple example of a RESTful web service. In this example:

Additional examples are listed in Learn More About RESTful Web Services.

Example 2-1 Simple RESTful Web Service

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
 
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {
 
   // Specifies that the method processes HTTP GET requests 
   @GET
   @Produces("text/plain")
   public String sayHello() {
      return "Hello World!";
   }
}

Parent topic: About RESTful Web Service Development

Defining the Root Resource Class

A root resource class is a Plain Old Java Object (POJO) that meets specific annotation requirements. The root resource class must satisfy one or both of the following statements:

Parent topic: Developing RESTful Web Services

Defining the Relative URI of the Root Resource and Subresources

Add the javax.ws.rs.Path annotation at the class level of the resource to define the relative URI of the RESTful web service. Such classes are referred to as root resource classes. You can add @Path on methods of the root resource class as well, to define subresources to group specific functionality.

The following sections describe how to define the relative URI of the root resource and subresources:

Parent topic: Developing RESTful Web Services

How to Define the Relative URI of the Resource Class (@Path)

The @Path annotation defines the relative URI path for the resource, and can be defined as a constant or variable value (referred to as "URI path template"). You can add the @Path annotation at the class or method level.

To define the URI as a constant value, pass a constant value to the @Path annotation. Preceding and ending slashes (/) are optional.

In Example 2-2, the relative URI for the resource class is defined as the constant value, /helloworld.

Example 2-2 Defining the Relative URI as a Constant Value

package samples.helloworld;
import javax.ws.rs.Path;
...
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {. . .}

To define the URI as a URI path template, pass one or more variable values enclosed in braces in the @Path annotation. Then, you can use the javax.ws.rs.PathParam annotation to extract variable information from the request URI, defined by the @Path annotation, and initialize the value of the method parameter, as described in How to Extract Variable Information from the Request URI (@PathParam).

In Example 2-3, the relative URI for the resource class is defined using a variable, enclosed in braces, for example, /users/{username}.

Example 2-3 Defining the Relative URI as a Variable Value

package samples.helloworld;
 
import javax.ws.rs.Path;
...
// Specifies the path to the RESTful service
@Path("/users/{username}")
public class helloWorld {. . .}
}

To further customize the variable, you can override the default regular expression of "[^/]+?" by specifying the expected regular expression as part of the variable definition. For example: 

@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]}")

In this example, the username variable will match only user names that begin with one uppercase or lowercase letter followed by zero or more alphanumeric characters or the underscore character. If the user name does not match the requirements, a 404 (Not Found) response will be sent to the client.

See the @Path annotation in the Jakarta EE 8 API Documentation.

Parent topic: Defining the Relative URI of the Root Resource and Subresources

How to Define the Relative URI of Subresources (@Path)

Add the javax.ws.rs.Path annotation to the method of a resource to define a subresource. Subresources enable users to group specific functionality for a resource.

In Example 2-4, if the request path of the URI is users/list, then the getUserList subresource method is matched and a list of users is returned.

Example 2-4 Defining a Subresource

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
 
// Specifies the path to the RESTful service
@Path("/users")
public class UserResource {
. . .
    @GET
    @Path("/list")
    public String getUserList() {
      ...
   }
}

Parent topic: Defining the Relative URI of the Root Resource and Subresources

What Happens at Runtime: How the Base URI is Constructed

The base URI is constructed as follows:

http://myHostName/contextPath/servletURI/resourceURI

  • myHostName—DNS name mapped to the Web Server. You can replace this with host:port which specifies the name of the machine running WebLogic Server and the port used to listen for requests.

  • contextPath—Name of the standalone Web application. The Web application name is specified in the META-INF/application.xml deployment descriptor in an EAR file or the weblogic.xml deployment descriptor in a WAR file. If not specified, it defaults to the name of the WAR file minus the .war extension. See context-root in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

  • servletURI—Base URI for the servlet context path. This path is configured as part of the packaging options defined in Table 4-1. Specifically, you can define the servlet context path by:

    • Updating the web.xml deployment descriptor to define the servlet mapping.

    • Adding a javax.ws.rs.ApplicationPath annotation to the class that extends javax.ws.rs.core.Application, if defined.

    If the servlet context path is configured using both options above, then the servlet mapping takes precedence. If you do not configure the servlet context path in your configuration using either of the options specified above, the WebLogic Server provides a default RESTful web service application context path, resources. See Building, Packaging, and Deploying RESTful Web Service Applications.

  • resourceURI—@Path value specified for the resource or subresource. This path may be constructed from multiple resources and subresources @Path values.

In Example 2-2, at runtime, if the context path for the WAR file is defined as rest and the default URI for the servlet (resources) is in effect, the base URI to access the resource is http://myServer:7001/rest/resources/helloworld.

In Example 2-3, at runtime, the base URI will be constructed based on the value specified for the variable. For example, if the user entered johnsmith as the username, the base URI to access the resource is http://myServer:7001/rest/resources/users/johnsmith.

Parent topic: Defining the Relative URI of the Root Resource and Subresources

Mapping Incoming HTTP Requests to Java Methods

JAX-RS uses Jakarta annotations to map an incoming HTTP request to a Java method. Table 2-2 lists the annotations available, which map to the similarly named HTTP methods.

Table 2-2 javax.ws.rs Annotations for Mapping HTTP Requests to Java Methods

Annotation Description Idempotent

@GET

Transmits a representation of the resource identified by the URI to the client. The format might be HTML, plain text, JPEG, and so on. See How to Transmit a Representation of the Resource (@GET).

Yes

@PUT

Creates or updates the representation of the specified resource identified by the URI. See How to Create or Update the Representation of the Resource (@PUT).

Yes

@DELETE

Deletes the representation of the resource identified by the URI. See How to Delete a Representation of the Resource (@DELETE).

Yes

@POST

Creates, updates, or performs an action on the representation of the specified resource identified by the URI. See How to Create, Update, or Perform an Action on a Representation of the Resource (@POST).

No

@HEAD

Returns the response headers only, and not the actual resource (that is, no message body). This is useful to save bandwidth to check characteristics of a resource without actually downloading it. See the @HEAD annotation in the Jakarta EE 8 API Documentation.

The HEAD method is implemented automatically if not implemented explicitly. In this case, the runtime invokes the implemented GET method, if present, and ignores the response entity, if set.

Yes

@OPTIONS

Returns the communication options that are available on the request/response chain for the specified resource identified by the URI. The Allow response header will be set to the set of HTTP methods supported by the resource and the WADL file is returned. See the @OPTIONS annotation in the Jakarta EE 8 API Documentation.

The OPTIONS method is implemented automatically if not implemented explicitly. In this case, the Allow response header is set to the set of HTTP methods supported by the resource and the WADL describing the resource is returned.

Yes

@HttpMethod

Indicates that the annotated method should be used to handle HTTP requests. See the @HttpMethod annotation in the Jakarta EE 8 API Documentation.

N/A

The following sections provide more information about the JAX-RS annotations used for mapping HTTP requests to Java methods.

Parent topic: Developing RESTful Web Services

About the Jersey Bookmark Sample

The examples referenced in the following sections are excerpted from the bookmark sample that is delivered with Jersey 2.x (JAX-RS 2.1 RI). The bookmark sample provides a Web application that maintains users and the browser bookmarks that they set.

The following table summarizes the resource classes in the sample, their associated URI path, and the HTTP methods demonstrated by each class.

Table 2-3 About the Jersey Bookmark Sample

Resource Class URI Path HTTP Methods Demonstrated

UsersResource

/users

GET

UserResource

/users/{userid}

GET, PUT, DELETE

BookmarksResource

/users/{userid}/bookmarks

GET, POST

BookmarkResource

/users/{userid}/bookmarks/{bmid}

GET. PUT, DELETE

The bookmark sample, and other Jersey samples, can be accessed in one of the following ways:

Parent topic: Mapping Incoming HTTP Requests to Java Methods

How to Transmit a Representation of the Resource (@GET)

The javax.ws.rs.GET annotation transmits a representation of the resource identified by the URI to the client. The format or the representation returned in the response entity-body might be HTML, plain text, JPEG, and so on. See the @GET annotation in the Jakarta EE 8 Specification APIs.

In Example 2-5, the annotated Java method, getBookmarkAsJsonArray, from the BookmarksResource class in the Jersey bookmark sample, will process HTTP GET requests. See About the Jersey Bookmark Sample.

Example 2-5 Mapping the HTTP GET Request to a Java Method (BookmarksResource Class)

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarksResource {
...
    @Path("{bmid: .+}")
    public BookmarkResource getBookmark(@PathParam("bmid") String bmid) {
        return new BookmarkResource(uriInfo, em, 
                userResource.getUserEntity(), bmid);
    }
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public JSONArray getBookmarksAsJsonArray() {
        JSONArray uriArray = new JSONArray();
        for (BookmarkEntity bookmarkEntity : getBookmarks()) {
            UriBuilder ub = uriInfo.getAbsolutePathBuilder();
            URI bookmarkUri = ub.
                    path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
                    build();
            uriArray.put(bookmarkUri.toASCIIString());
        }
        return uriArray;
    }
...
}

In Example 2-6, the annotated Java method, getBookmark, from the BookmarkResource class in the Jersey bookmark sample, will process HTTP GET requests. This example shows how to process the JSON object that is returned. See About the Jersey Bookmark Sample.

Example 2-6 Mapping the HTTP GET Request to a Java Method (BookmarkResource Class)

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarkResource {
...
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public JSONObject getBookmark() {
        return asJson();
    }
...
    public JSONObject asJson() {
        try {
            return new JSONObject()
                    .put("userid", bookmarkEntity.getBookmarkEntityPK().getUserid())
                    .put("sdesc", bookmarkEntity.getSdesc())
                    .put("ldesc", bookmarkEntity.getLdesc())
                    .put("uri", bookmarkEntity.getUri());
        } catch (JSONException je){
            return null;
        }
    }
}

Parent topic: Mapping Incoming HTTP Requests to Java Methods

How to Create or Update the Representation of the Resource (@PUT)

The javax.ws.rs.PUT annotation creates or updates the representation of the specified resource identified by the URI. See the @PUT annotation in the Jakarta EE 8 Specification APIs.

In Example 2-7, the annotated Java method, putBookmark, from the BookmarkResource class in the Jersey bookmark sample, will process HTTP PUT requests and update the specified bookmark. See About the Jersey Bookmark Sample.

Example 2-7 Mapping the HTTP PUT Request to a Java Method

import javax.ws.rs.PUT;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarkResource {
...
    @PUT
    @Consumes(MediaType.APPLICATION_JSON)
    public void putBookmark(JSONObject jsonEntity) throws JSONException {
        
        bookmarkEntity.setLdesc(jsonEntity.getString("ldesc"));
        bookmarkEntity.setSdesc(jsonEntity.getString("sdesc"));
        bookmarkEntity.setUpdated(new Date());
        
        TransactionManager.manage(new Transactional(em) { 
             public void transact() {
            em.merge(bookmarkEntity);
        }});
    }    
 
}

Parent topic: Mapping Incoming HTTP Requests to Java Methods

How to Delete a Representation of the Resource (@DELETE)

The javax.ws.rs.DELETE annotation deletes the representation of the specified resource identified by the URI. The response entity-body may return a status message or may be empty. See the @DELETE annotation in the Jakarta EE 8 Specification APIs.

In Example 2-8, the annotated Java method, deleteBookmark, from the BookmarkResource class in the Jersey bookmark sample, will process HTTP DELETE requests, and delete the specified bookmark. See About the Jersey Bookmark Sample.

Example 2-8 Mapping the HTTP DELETE Request to a Java Method

import javax.ws.rs.DELETE;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarkResource {
...
    @DELETE
    public void deleteBookmark() {
        TransactionManager.manage(new Transactional(em) { 
          public void transact() {
            UserEntity userEntity = bookmarkEntity.getUserEntity();
            userEntity.getBookmarkEntityCollection().remove(bookmarkEntity);
            em.merge(userEntity);
            em.remove(bookmarkEntity);
        }});
    }    
}

Parent topic: Mapping Incoming HTTP Requests to Java Methods

How to Create, Update, or Perform an Action on a Representation of the Resource (@POST)

The javax.ws.rs.POST annotation creates, updates, or performs an action on the representation of the specified resource identified by the URI. See the @POST annotation in the Jakarta EE 8 Specification APIs.

In Example 2-9, the annotated Java method, postForm, from the BookmarksResource class in the Jersey bookmark sample, will process HTTP POST requests, and update the specified information. See About the Jersey Bookmark Sample.

Example 2-9 Mapping the HTTP POST Request to a Java Method

import javax.ws.rs.POST;
import javax.ws.rs.Produces;
...
public class BookmarksResource {
...
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response postForm(JSONObject bookmark) throws JSONException {
        final BookmarkEntity bookmarkEntity = new BookmarkEntity(getBookmarkId(bookmark.getString("uri")), 
                userResource.getUserEntity().getUserid());
 
        bookmarkEntity.setUri(bookmark.getString("uri"));
        bookmarkEntity.setUpdated(new Date());
        bookmarkEntity.setSdesc(bookmark.getString("sdesc"));
        bookmarkEntity.setLdesc(bookmark.getString("ldesc"));
        userResource.getUserEntity().getBookmarkEntityCollection().add(bookmarkEntity);
 
        TransactionManager.manage(new Transactional(em) { 
           public void transact() {
            em.merge(userResource.getUserEntity());
        }});
 
        URI bookmarkUri = uriInfo.getAbsolutePathBuilder().
                path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
                build();
        return Response.created(bookmarkUri).build();
    }
}

Parent topic: Mapping Incoming HTTP Requests to Java Methods

Customizing Media Types for the Request and Response Messages

To customize the media types for request and response messages, add the javax.ws.rs.Consumes or javax.ws.rs.Produces annotation at the class level of the resource. This task is described in the following sections:

Parent topic: Developing RESTful Web Services

How To Customize Media Types for the Request Message (@Consumes)

The javax.ws.rs.Consumes annotation enables you to specify the MIME media types of representations a resource can consume that were sent from the client. The @Consumes annotation can be specified at both the class and method levels and more than one media type can be declared in the same @Consumes declaration.

If there are no methods in a resource that can consume the specified MIME media types, the runtime returns an HTTP 415 Unsupported Media Type error.

See the @Consumes annotation in the Jakarta EE 8 Specification APIs.

In Example 2-10, the @Consumes annotation defined for the Java class, helloWorld, specifies that the class produces messages using the text/plain MIME media type.

Example 2-10 Customizing the Media Types for the Request Message Using @Consumes

package samples.consumes;

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...
@Path("/helloworld")
public class helloWorld {
...
    @POST
    @Consumes("text/plain")
    public void postMessage(String message) {
       // Store the message
   }
}

Parent topic: Customizing Media Types for the Request and Response Messages

How To Customize Media Types for the Response Message (@Produces)

The javax.ws.rs.Produces annotation enables you to specify the MIME media types of representations a resource can produce and send back to the client. The @Produces annotation can be specified at both the class and method levels and more than one media type can be declared in the same @Produces declaration.

If there are no methods in a resource that can produce the specified MIME media types, the runtime returns an HTTP 406 Not Acceptable error.

See the @Produces annotation in the Jakarta EE 8 Specification APIs.

In Example 2-11, the @Produces annotation specified for the Java class, SomeResource, specifies that the class produces messages using the text/plain MIME media type. The doGetAsPlainText method defaults to the MIME media type specified at the class level. The doGetAsHtml method overrides the class-level setting and specifies that the method produces HTML rather than plain text.

Example 2-11 Customizing the Media Types for the Response Using @Produces

package samples.produces;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;

@Path("/myResource")
@Produces("text/plain")
public class SomeResource {
    @GET
    public String doGetAsPlainText() { ... }

    @GET
    @Produces("text/html")
    public String doGetAsHtml() { ... }
}

Parent topic: Customizing Media Types for the Request and Response Messages

What Happens At Runtime: How the Resource Method Is Selected for Response Messages

If a resource class is capable of producing more that one MIME media type, then the resource method that is selected corresponds to the acceptable media type declared in the Accept header of the HTTP request. In Example 2-11, if the Accept header is Accept: text/html, then the doGetAsPlainText method is invoked.

If multiple MIME media types are included in the @Produces annotation and both are acceptable to the client, the first media type specified is used. In Example 2-11, if the Accept header is Accept: application/html, application/text, then the doGetAsHtml method is invoked and the application/html MIME media type is used as it is listed first in the list.

Parent topic: Customizing Media Types for the Request and Response Messages

Extracting Information From the Request Message

The javax.ws.rs package defines a set of annotations that enable you extract information from the request message to inject into parameters of your Java method. These annotations are listed and described in Table 2-4.

Table 2-4 javax.ws.rs Annotations for Extracting Information From the Request Message

Annotation Description

@BeanParam

Inject aggregated request parameters into a single bean. See the @BeanParam annotation in the Jakarta EE 8 API Documentation.

For additional usage information, see Parameter Annotations (@*Param) in the Jersey 2.29 User Guide.

@CookieParam

Extract information from the HTTP cookie-related headers to initialize the value of a method parameter. See the @CookieParam annotation in the Jakarta EE 8 API Documentation.

@DefaultValue

Define the default value of the request metadata that is bound using one of the following annotations: @CookieParam, @FormParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam. See How to Define the DefaultValue (@DefaultValue).

@Encoded

Enable encoding of a parameter value that is bound using one of the following annotations: @FormParam, @MatrixParam, @PathParam, or @QueryParam. See Enabling the Encoding Parameter Values (@Encoded).

@FormParam

Extract information from an HTML form of the type application/x-www-form-urlencoded. See the @FormParam annotation in the Jakarta EE 8 API Documentation.

@HeaderParam

Extract information from the HTTP headers to initialize the value of a method parameter. See the @HeaderParam annotation in the Jakarta EE 8 API Documentation.

@MatrixParam

Extract information from the URI path segments to initialize the value of a method parameter. See the @MatrixParam annotation in the Jakarta EE 8 API Documentation.

@PathParam

Define the relative URI as a variable value (referred to as "URI path template"). See How to Extract Variable Information from the Request URI (@PathParam).

@QueryParam

Extract information from the query portion of the request URI to initialize the value of a method parameter. See How to Extract Request Parameters (@QueryParam).

Parent topic: Developing RESTful Web Services

How to Extract Variable Information from the Request URI (@PathParam)

Add the javax.ws.rs.PathParam annotation to the method parameter of a resource to extract the variable information from the request URI and initialize the value of the method parameter. You can define a default value for the variable value using the @DefaultValue annotation, as described in How to Define the DefaultValue (@DefaultValue).

In Example 2-12, the @PathParam annotation assigns the value of the username variable that is defined as part of the URI path by the @Path annotation to the userName method parameter.

Example 2-12 Extracting Variable Information From the Request URI

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.PathParam;
 
// Specifies the path to the RESTful service
@Path("/users")
public class helloWorld {
. . .
    @GET
    @Path("/{username}")
    @Produces("text/xml")
    public String getUser(@PathParam("username") String userName) {
      ...
   }
}

Parent topic: Extracting Information From the Request Message

How to Extract Request Parameters (@QueryParam)

Add the javax.ws.rs.QueryParam annotation to the method parameter of a resource to extract information from the query portion of the request URI and initialize the value of the method parameter.

The type of the annotated method parameter can be any of the following:

  • Primitive type (int, char, byte, and so on)

  • User-defined type

  • Constructor that accepts a single String argument

  • Static method named valueOf or fromString that accepts a single String argument (for example, integer.valueOf(String))

  • List<T>, Set<T>, or SortedSet<T>

If the @QueryParam annotation is specified but the associated query parameter is not present in the request, then the parameter value will set as an empty collection for List, Set or SortedSet, the Java-defined default for primitive types, and NULL for all other object types. Alternatively, you can define a default value for the parameter using the @DefaultValue annotation, as described in How to Define the DefaultValue (@DefaultValue).

See the @QueryParam annotation in the Jakarta EE 8 Specification APIs.

In Example 2-13, if the step query parameter exists in the query component of the request URI, the value will be assigned to the step method parameter as an integer value. If the value cannot be parsed as an integer value, then a 400 (Client Error) response is returned. If the step query parameter does not exist in the query component of the request URI, then the value is set to NULL.

Example 2-13 Extracting Request Parameters (@QueryParam)

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.QueryParam;
...
    @Path("smooth")
    @GET
    public Response smooth(@QueryParam("step") int step) 
    { ... }
}

Parent topic: Extracting Information From the Request Message

How to Define the DefaultValue (@DefaultValue)

Add the javax.ws.rs.DefaultValue annotation to define the default value of the request metadata that is bound using one of the following annotations: @CookieParam, @FormParam, @HeaderParam, @MatrixParam, @PathParam, or @QueryParam. See the @DefaultValue annotation in the Jakarta EE 8 Specification APIs.

In Example 2-14, if the step query parameter does not exist in the query component of the request URI, the default value of 2 will be assigned to the step parameter.

Example 2-14 Defining the Default Value (@DefaultValue)

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.QueryParam;
...
    @Path("smooth")
    @GET
    public Response smooth(@DefaultValue("2") @QueryParam("step") int step) 
    { ... }
}

Parent topic: Extracting Information From the Request Message

Enabling the Encoding Parameter Values (@Encoded)

Add the javax.ws.rs.Encoded annotation at the class or method level to enable the encoding of a parameter value that is bound using one of the following annotations: @FormParam, @MatrixParam, @PathParam, or @QueryParam. If specified at the class level, parameters for all methods in the class will be encoded. See the @Encoded annotation in the Jakarta EE 8 Specification APIs.

In Example 2-15, the @Encoded annotation enables the encoding of parameter values bound using the @PathParam annotation.

Example 2-15 Encoding Parameter Values

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.PathParam;
import javax.ws.rs.Encoded;
 
// Specifies the path to the RESTful service
@Path("/users")
public class helloWorld {
. . .
    @GET
    @Path("/{username}")
    @Produces("text/xml")
    @Encoded
    public String getUser(@PathParam("username") String userName) {
      ...
   }
}

Parent topic: Extracting Information From the Request Message

Building Custom Response Messages

Instead of the default response codes, you can customize the response codes returned or include additional metadata information in the response.

By default, JAX-RS responds to HTTP requests using the default response codes defined in the HTTP specification, such as 200 OK for a successful GET request and 201 CREATED for a successful PUT request.

For example, you might want to include the Location header to specify the URI to the newly created resource. You can modify the response message returned using the javax.ws.rs.core.Response class.

An application can extend the Response class directly or use one of the static Response methods to create a javax.ws.rs.core.Response.ResponseBuilder instance and build the Response instance. The methods you can use are defined in Table 2-5. For more information, see the Response methods in the Jakarta EE 8 Specification APIs.

Table 2-5 Creating a Response Instance Using the ResponseBuilder Class

Method Description

created()

Creates a new ResponseBuilder instance and sets the Location header to the specified value.

fromResponse()

Creates a new ResponseBuilder instance and copies an existing response.

noContent()

Creates a new ResponseBuilder instance and defines an empty response.

notAcceptable()

Creates a new ResponseBuilder instance and defines a unacceptable response.

notModified()

Creates a new ResponseBuilder instance and returns a not-modified status.

ok()

Creates a new ResponseBuilder instance and returns an OK status.

seeOther()

Creates a new ResponseBuilder instance for a redirection.

serverError()

Creates a new ResponseBuilder instance and returns a server error status.

status()

Creates a new ResponseBuilder instance and returns the specified status.

temporaryRedirect()

Creates a new ResponseBuilder instance for a temporary redirection.

Once you create a ResponseBuilder instance, you can call the methods defined in Table 2-6 to build a custom response. Then, call the build() method to create the final Response instance. See the Response.ResponseBuilder methods in the Jakarta EE 8 Specification APIs.

Table 2-6 ResponseBuilder Methods for Building a Custom Response

Method Description

allow()

Sets the list of allowed methods for the resource.

build()

Creates the Response instance from the current ResponseBuilder instance.

cacheControl()

Sets the cache control.

clone()

Create a copy of the ResponseBuilder to preserve its state.

contentLocation()

Sets the content location.

cookie()

Add cookies to the response.

encoding()

Sets the message entity content encoding.

entity()

Defines the entity.

expires()

Sets the expiration date.

header()

Adds a header to the response.

language()

Sets the language.

lastModified()

Set the last modified date.

link()

Adds a link header.

links()

Adds one or more link headers.

location()

Sets the location.

newInstance()

Creates a new ResponseBuilder instance.

replaceAll()

Replaces all existing headers with the newly supplied headers.

status()

Sets the status.

tag()

Sets an entity tag.

type()

Sets the response media type.

variant()

Set representation metadata.

variants()

Add a Vary header that lists the available variants.

Example 2-16 shows how to build a Response instance using ResponseBuilder. In this example, the standard status code of 200 OK is returned and the media type of the response is set to text/html. A call to the build() method creates the final Response instance.

Example 2-16 Building a Custom Response

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.ResponseBuilder;
...
@Path("/content")
public class getDocs {
   @GET
   @Path("{id}")
   public Response getHTMLDoc(@PathParm("id") int docId)
   {
      Document document = ...;
      ResponseBuilder response = Response.ok(document);
      response.type("text/html");
      return response.build();
   }
}

If you wish to build an HTTP response using a generic type, to avoid type erasure at runtime you need to create a javax.ws.rs.core.GenericEntity object to preserve the generic type. See the GenericEntity methods in the Jakarta EE 8 Specification APIs.

Example 2-17 provides an example of how to build an HTTP response using GenericEntity to preserve the generic type.

Example 2-17 Building a Custom Response Using a Generic Type

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.ResponseBuilder;
javax.ws.rs.core.GenericEntity;
...
@Path("/content")
public class getDocs {
   @GET
   @Path("{id}")
   public Response getHTMLDoc(@PathParm("id") int docId)
   {
      Document document = ...;
      List<String> list = new ArrayList<String>();
      GenericEntity<List<String>> entity = new GenericEntity<List<String>>(list) {};
      ...
      ResponseBuilder response = Response.ok(document);
      response.entity(entity);
      return response.build();
   }
}

Parent topic: Developing RESTful Web Services

Mapping HTTP Request and Response Entity Bodies Using Entity Providers

HTTP request and response entity bodies automatically support a set of Java types that can be utilized by your RESTful web service. These Java types are listed in Table 2-7.

Table 2-7 Java Types Supported for HTTP Request and Response Entity Bodies

Java Type Supported Media Types

byte[]

All media types (*/*)

java.lang.String

All media types (*/*)

java.io.InputStream

All media types (*/*)

java.io.Reader

All media types (*/*)

java.io.File

All media types (*/*)

javax.activation.DataSource

All media types (*/*)

javax.xml.transform.Source

XML media types (text/xml, application/xml, and application/*+xml) and JSON media types (application/json, application/*+json)

javax.xml.bind.JAXBElement and application-supplied JAXB classes

XML media types (text/xml, application/xml, and application/*+xml)

MultivaluedMap<String,String>

Form content (application/x-www-form-urlencoded)

StreamingOutput

All media types (*/*), MessageBodyWriter only

If your RESTful web service utilizes a type that is not listed in Table 2-7, you must define an entity provider, by implementing one of the interfaces defined in Table 2-8, to map HTTP request and response entity bodies to method parameters and return types.

Table 2-8 Entity Providers for Mapping HTTP Request and Response Entity Bodies to Method Parameters and Return Types

Entity Provider Description

javax.ws.rs.ext.MessageBodyReader

Maps an HTTP request entity body to a method parameter for an HTTP request. Optionally, you can use the @Consumes annotation to specify the MIME media types supported for the entity provider, as described in Customizing Media Types for the Request and Response Messages.

For example:

@Consumes("application/x-www-form-urlencoded")
@Provider
public class FormReader implements MessageBodyReader<NameValuePair> { ... }

javax.ws.rs.ext.MessageBodyWriter

Maps the return value to an HTTP response entity body for an HTTP response. Optionally, you can use the @Produces annotation to specify the MIME media types supported for the entity provider, as described in Customizing Media Types for the Request and Response Messages.

For example:

@Produces("text/html")
@Provider
public class FormWriter implements 
        MessageBodyWriter<Hashtable<String, String>> { ... }

Note:

Jersey JSON provides a set of JAX-RS MessageBodyReader and MessageBodyWriter providers distributed with the Jersey JSON extension modules. See JSON in the Jersey 2.29 User Guide.

The following code excerpt provides an example of a class that contains a method (getClass) that returns a custom type, and that requires you to write an entity provider. 

public class Class1
{
  public String hello() { return "Hello"; }
  public Class2 getClass(String name) { return new Class2(); };
}
 
public class Class2
{
  public Class2() { }
}

Parent topic: Developing RESTful Web Services

Accessing the Application Context

The javax.ws.rs.core.Context annotation enables you to access information about the application deployment context and the context of individual requests. Table 2-9 summarizes the context types that you can access using the @Context annotation. For more information, see the @Context annotation in the Jakarta EE 8 Specification APIs.

Table 2-9 Context Types

Use this context type . . . To . . .

HttpHeaders

Access HTTP header information.

Providers

Lookup Provider instances based on a set of search criteria.

Request

Determine the best matching representation variant and to evaluate whether the current state of the resource matches any preconditions defined. See Using Conditional GETs.

SecurityContext

Access the security context and secure the RESTful web service. See Securing RESTful Web Services Using SecurityContext.

UriInfo

Access application and request URI information. See Building URIs.

Parent topic: Developing RESTful Web Services

Building URIs

You can use javax.ws.rs.core.UriInfo to access application and request URI information.

Specifically, UriInfo can be used to return the following information:

  • Deployed application's base URI

  • Request URI relative to the base URI

  • Absolute path URI (with or without the query parameters)

Using UriInfo, you can return a URI or javax.ws.rs.core.UriBuilder instance. UriBuilder simplifies the process of building URIs, and can be used to build new or extend existing URIs.

The UriBuilder methods perform contextual encoding of characters not permitted in the corresponding URI component based on the following rules:

Example 2-18 shows how to obtain an instance of UriInfo using @Context and use it to return an absolute path of the request URI as a UriBuilder instance. Then, using UriBuilder build a URI for a specific user resource by adding the user ID as a path segment and store it in an array. In this example, the UriInfo instance is injected into a class field. This example is excerpted from the bookmark sample, as described in About the Jersey Bookmark Sample.

Example 2-18 Building URIs

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.core.UriBuilder;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.core.Context;
...
@Path("/users/")
public class UsersResource {
 
    @Context UriInfo uriInfo;
 
    ...
 
    @GET
    @Produces("application/json")
    public JSONArray getUsersAsJsonArray() {
        JSONArray uriArray = new JSONArray();
        for (UserEntity userEntity : getUsers()) {
            UriBuilder ub = uriInfo.getAbsolutePathBuilder();
            URI userUri = ub
                  .path(userEntity.getUserid())
                  .build();
            uriArray.put(userUri.toASCIIString());
        }
        return uriArray;
    }
}

Parent topic: Developing RESTful Web Services

Using Conditional GETs

A conditional GET enables you to evaluate one or more preconditions before processing a GET request. If the preconditions are met, a Not Modified (304) response can be returned rather than the normal response, potentially reducing bandwidth and improving server performance.

JAX-RS provides the javax.ws.rs.core.Request contextual interface enabling you to perform conditional GETs. You call the evaluatePreconditions() method and pass a javax.ws.rs.core.EntityTag, the last modified timestamp (as a java.util.Date object), or both. The values are compared to the If-None-Match or If-Not-Modified headers, respectively, if these headers are sent with the request.

If headers are included with the request and the precondition values match the header values, then the evaluatePreconditions() methods returns a predefined ResponseBuilder response with a status code of Not Modified (304). If the precondition values do no match, the evaluatePreconditions() method returns null and the normal response is returned, with 200, OK status.

Example 2-19 shows how to pass the EntityTag to the evaluatePreconditions() method and build the response based on whether the preconditions are met.

Example 2-19 Using Conditional GETs

...
@Path("/employee/{joiningdate}")
public class Employee {
 
    Date joiningdate;
    public Employee(@PathParam("joiningdate") Date joiningdate, @Context Request req, 
            @Context UriInfo ui) {
 
        this.joiningdate = joiningdate;
        ...
        this.tag = computeEntityTag(ui.getRequestUri());
        if (req.getMethod().equals("GET")) {
            Response.ResponseBuilder rb = req.evaluatePreconditions(tag);
            // Preconditions met
            if (rb != null) {
                return rb.build();
            }
            // Preconditions not met
            rb = Response.ok();
            rb.tag(tag);
            return rb.build();
        }
    }
}

Parent topic: Developing RESTful Web Services

Accessing the WADL

The Web Application Description Language (WADL) is an XML-based file format that describes your RESTful web services application. By default, a basic WADL is generated at runtime and can be accessed from your RESTful web service by issuing a GET on the /application.wadl resource at the base URI of your RESTful application.

For example:

GET http://<path_to_REST_app>/application.wadl

Alternatively, you can use the OPTIONS method to return the WADL for particular resource.

Example 2-20 shows an example of a WADL for the simple RESTful web service shown in Example 2-1.

Example 2-20 Example of a WADL

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
   <doc xmlns:jersey="http://jersey.dev.java.net/" 
              jersey:generatedBy="Jersey: 0.10-ea-SNAPSHOT 08/27/2008 08:24 PM"/>
   <resources base="http://localhost:9998/">        
      <resource path="/helloworld">            
         <method name="GET" id="sayHello">
            <response>
               <representation mediaType="text/plain"/>
            </response>
         </method>
      </resource>
   </resources>
</application>

Parent topic: Developing RESTful Web Services

More Advanced RESTful Web Service Tasks

The Jersey 2.29 User Guide provides information about more advanced RESTful web service development tasks. See this guide, available at https://eclipse-ee4j.github.io/jersey.github.io/documentation/2.29/index.html, for the following topics:

Parent topic: Developing RESTful Web Services