Creating a JAX-RS web service

Before you begin

To deploy the web service you need to have a server which has Java™ 5.0 or later JVM support defined and started. This includes:
  • WebSphere® Application Server v7.0 or v8.0, selecting to install the Feature Pack for Web 2.0 AND MOBILE and the tools for WebSphere Application Server development
By default a server is created for you when you install WebSphere Application Server. This server can be seen in the Servers view.

If you choose to deploy to a server other than WebSphere Application Server, you cannot use the IBM® JAX-RS library, and must install and configure your own JAX-RS libraries through the Project Facets > JAX-RS preferences page.

Create a JAX-RS enabled web project

About this task

The JAX-RS web service needs to reside in a project with the JAX-RS facet enabled.
Restriction: [Liberty] To use the JAX-RS 2.0, or higher, APIs, create a User Library and add the com.ibm.ws.javaee.jaxrs.2.0_1.0.0.jar that is in the dev/api/spec folder of the Liberty runtime. Move this User Library ahead of the Liberty server class path container in the project's Java build path.

[WebSphere Application Server traditional] WebSphere Application Server traditional V9 supports JAX-RS 1.1 and higher. The version of JAX-RS that you use in your project must match the version of JAX-RS that you use in your installation of WebSphere Application Server traditional V9. If these versions do not match, the tools display a warning when you deploy your project to the server. If you create a JAX-RS project without specifying a facet level, the tools use JAX-RS 2.0 by default.

[WebSphere Application Server traditional] When you add a JAX-RS 1.1 module to a web project, the tools add the following files to the class path container:
com.ibm.ws.jaxrs.jar
com.ibm.ws.prereq.jaxrs.jar
javax.j2ee.jaxrs.jar
[WebSphere Application Server traditional] When you add a JAX-RS 2.0, or higher, module to a web project, the tools add the following files to the class path container:
com.ibm.ws.jaxrs20.jar
com.ibm.ws.prereq.jaxrs20.jar
javax.ws.rs-api-2.0.jar

Procedure

  1. In the Java EE perspective, right-click your enterprise application project and select New > Web Project to open the web project wizard.
  2. In the Name field, type a name for your new web project.
  3. In the Project Templates section, select the type of web template you want to use. select Simple to create a simple web project.
  4. In the Programming Model section, select the programming model that you want to use: select Java EE programming model. Click Next to configure your new web project.
  5. On the deployment page, from the list of available configuration options, click Deployment to open the Deployment configuration page.
    • You can change Target runtime by selecting another one from the drop-down box. Click Change Features to open the Project Facets window. On the Project Facets page, select JAX-RS (REST Web Services), and click OK.
    • Click Add support for WebSphere bindings and extensions or clear this field.
    • In the Web module version field, select the web module version that you want to use.
    • In the EAR membership field, click Add project to an EAR, if you want to include EAR membership; clear this field if you do not want to add the web project to an EAR file.
    • In the EAR project name field, the name of your existent EAR file appears. You can click Browse to select a different EAR file.
    Note: The deployment option is not available if you selected the Client-side only programming model for your new web project.
  6. From the list of available configuration options, click REST Services.
    1. In the JAX-RS Implementation Library field select the library for you server version, for example IBM WebSphere Application Server v8.0 JAX-RS Library or IBM WebSphere Application Server v8.5 JAX-RS Library.
      Learn more about libraries: The JAX-RS libraries for each WebSphere Test Environment you have installed will be listed in this drop-down box. If you want to use a non-WebSphere library, it can be imported using the User Libraries preference page. If you select User Library, you can launch the User Libraries preference page and add a library. Once a project has been created, you can change the library by right-clicking your project and selecting Preferences > Project Facets > JAX-RS. You can also select to have the wizard not configure the library for you, in which case you must manually configure the classpath.
    2. If you are using a version of WebSphere Application Server earlier than v8, check Include library with this application and select to include it as a Shared Library. This adds JAX-RS jars to the classpath, as well as adding a Shared Library entry in the enhanced EAR.
    3. Update Deployment Descriptor is selected by default because you will need to use a web.xml to configure security constraints and other behavior. A web.xml will be generated and updated with JAX-RS servlet information even if you have selected to not generate a deployment descriptor earlier in wizard. This option is only available when the Web Modules facet selected is v3.0 or higher.
    4. If you have chosen to update the deployment descriptor, you will be able to change the servlet name and servlet class name, and change the URL mapping patterns.
  7. From the list of available configuration options, click Java to open the Java configuration page.
    • In the Source folders on build path field, accept the default src directory, or click Add Folder, Edit... or Remove to specify a folder for your source files.
    • In the Default output folder: field, specify a folder for your output files or accept the default value (WebContent\WEB-INF\classes).
  8. From the list of available configuration options, click Web Module. On the Web Module configuration page:
    • In the Context root field, type the name of your web project root, or accept the default (which is the name of your web project).
    • In the Content directory field, type the name of your content directory, or accept the default (WebContent).
    • Select Generate web.xml deployment descriptor if you want to create a deployment descriptor. You can also add a deployment descriptor to your web module later.
  9. Click Finish.

Create a JAX-RS web service

Procedure

  1. In your Web project, create a package (right-click Java Resources > src and select New > Package). Import the classes for the web service into the package.
  2. Open WebContent/WEB-INF/web.xml. In the Design view, select the Servlet JAX-RS Servlet and click Add and add an Initialization parameter to the JAX-RS servlet, leaving the name and value fields empty. Save web.xml ignoring any errors that might be displayed.
  3. In the Markers view, select the web.xml error about the param-name, right-click and select Quick Fix. Browse to the application and select.
  4. Add the EAR containing the JAX-RS project to the server and start the server.

Results

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.

Editing a JAX-RS project

Once you have created a JAX-RS web service, you can edit it by right-clicking the project and selecting Properties > Project Facets > JAX-RS. From this page you can change:
  • Library type
  • JAX-RS servlet name
  • JAX-RS servlet class name
  • URL mapping patterns
For example if you migrate your project to a different server, you can change the library provider to one supported by the new server.