Deploying JAX-RS web applications

After you assemble your Java™ API for RESTful Web Services (JAX-RS) web application, you can deploy the web application archive (WAR) package or the enterprise archive (EAR) package onto the application server.

Before you begin

To deploy a JAX-RS web application, you need a WAR package or EAR package that is configured and enabled for RESTful services.

About this task

Every web application must have a context root for the web application to deploy successfully. A context root for each Web module is defined in the application deployment descriptor during application assembly or during application deployment. The context root is combined with the defined servlet mapping from the WAR file to compose the full URL that users type to access the servlet. The context root for each deployed web application must be unique on the server. The context root can also be empty. For instance, if a Web application used a context root of sample/application/, the web application request URL begins with http://<hostname>:<port>/sample/application/.

The URL pattern of a servlet is appended to the context root of the Web application. For example, if the context root is sample/application/ and the servlet URL mapping is rest/api/*, the base URI for the JAX-RS web application is http://<hostname>:<port>/sample/application/rest/api.

Procedure

Deploy the JAX-RS web application WAR package or EAR package onto the application server.
Read about installing enterprise application files to learn more about deploying web applications.

Results

The JAX-RS web application is deployed and ready for your business use.

Deployment of a Java API for RESTful Web Services (JAX-RS) web application is successful if you can access the application by typing a Uniform Resource Locator (URL) in a browser or if you can access the application by following a link. If you cannot access your application, follow these steps to eliminate some common errors that can occur during deployment.

Avoid trouble:

Use the following tips to resolve common errors during deployment of JAX-RS web applications.

An HTTP 404 Not Found error message is sent back to the client in the server response.
To resolve this problem, take the following actions:
  • Verify that the root resource classes are annotated with a @javax.ws.rs.Path annotation and that the value in the annotation is correct. Root resource classes without a @Path annotation are not registered with the JAX-RS runtime. To learn more, see the defining the URI patterns for resources in RESTful applications information.
  • Verify that the root resource class is added to the set of classes that are returned from the getClasses() method for the subclasses of the javax.ws.rs.core.Application class. Classes that are not registered in the subclasses of the javax.ws.rs.core.Application class are not recognized by the JAX-RS runtime environment. To learn more, see the defining the URI patterns for resources in RESTful applications information.
  • Verify that the web.xml configuration is correct with the expected URL patterns. For more information, see the web.xml for JAX-RS servlets and filters information.
  • Verify that the URL that is being used is correct and includes the context root. If you are using a servlet, the servlet URL pattern is a part of the final URL. Using a filter might be more suitable in your web application. For more information, see the web.xml file for JAX-RS servlets and filters information.
An HTTP 405 Method Not Allowed error message is sent back to the client in the server response.
If a request URL's servlet URI matches a resource method 's path value, but the HTTP method sent does not match the method annotation, then an HTTP status code 405 Method Not Allowed is returned.

In the following code example the request URL ends with sayhello but the request contains a POST instead of a GET, so the 405 is returned.

@javax.ws.rs.Path("helloworld")
public class SampleResource {

...

@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...

To resolve this problem, verify that the HTTP method sent matches the method annotation.

An HTTP 406 Not Acceptable error message is automatically being sent back to the client in the server response.
To resolve this problem, take the following actions:
  • Verify that the Accept HTTP request header in the incoming request is correct. To learn more, see the Implementing content negotiation that is based on HTTP headers information.
  • Verify that the @javax.ws.rs.Produces value on the resource method or resource class is compatible with the incoming Accept HTTP request header. To learn more, see the defining media types for resources in RESTful applications.
An HTTP 415 Unsupported Media Type error message is automatically being sent back to the client in the server response.
To resolve this problem, take the following actions:
  • Verify that the Content-Type HTTP request header in the incoming request is correct and is being sent. To learn more, see the defining media types for resources in RESTful applications.
  • Verify that the @javax.ws.rs.Consumes value on the resource method or resource class is compatible with the incoming Content-Type HTTP request header.
An HTTP 204 No Content response status is automatically being sent back to the client in the server response.

To resolve this problem, determine if a null response in your resource should result in a 204 No Content response code.

For information about known problems and their resolution, see the IBM Support page.

IBM® Support has documents that can save you time gathering information that is needed to resolve this problem.