Learning the JAX-RS basics: How to write a simple REST interface for accessing System properties with JAX-RS (Java API for RESTful Services).

Why yet another JAX-RS basics tutorial?

Just after Labour Day Labor Day last year, I was debugging a problem involving JAX-RS in the Liberty profile. I wasn’t even sure I knew what JAX-RS stood for. Still, to debug the problem I needed a sample JAX-RS application. Fast.

I decided this as an opportunity to learn how to code to JAX-RS (which, I learned, stands for Java API for RESTful Services). But while everything I read about JAX-RS was probably 100% accurate, it suffered from having been written by someone who understood JAX-RS. Sure, tutorials might be out there, but I didn’t find a helpful one.

About the sample application

Any good tutorial needs a sample application. For simplicity, and to focus just on the JAX-RS-ness, I decided to write a simple REST interface for accessing system properties.

I decided I would simply expose the Java system properties using REST:

System/properties

This should return a JSON response like this:

{ "property1" : "propertyValue", "property2" : "propertyValue" }

And the individual properties to be available from:

System/property/<propertyName>

which should return a JSON response like this:

"<propertyName>" : "propertyValue"

Building the application

Here’s how I built the application. I used the Eclipse IDE for Java EE, WDT 8.5.5 and Liberty profile 8.5.5 for this; I’m going to assume you have some basic knowledge of these tools.

Step 1 – Creating the Web project

  1. Create a new Web project based on the REST Services template, then click Next.
  2. On the Deployment page, configure the project to use an existing Liberty profile installation and clear the add it to an EAR check box.
  3. On the REST Services page, disable the JAX-RS option and clear the Update Deployment Descriptor check box. This gets rid of the errors so that you can click Finish.

Step 2 – Creating the JAX-RS Java Bean

  1. JAX-RS is based on the idea of annotated Java classes, so create a Java class with the name net.wasdev.jaxrs.SystemProperties.
  2. To make this into a JAX-RS bean, annotate it using the javax.ws.rs.Path annotation like this:
    
    @Path("System/properties")
    
    public class SystemProperties {
    
    }
    
    

    This says “this class is a resource and can be accessed from the ‘System/properties’ URL”.

    This isn’t very useful though because we can’t do anything with the resource. With REST, read access is mapped to the http GET method, so in order to provide data you provide a getter method annotated with the javax.ws.rs.GET annotation.

  3. Create a getSystemProperties method like this one:
    @GET
    
    public Map<String, String> getSystemProperties() {
    
     Map<String, String> result = new HashMap<>();
    
     Properties props = System.getProperties();
    
     for (Map.Entry<Object, Object> entry : props.entrySet()) {
    
     result.put((String)entry.getKey(), (String)entry.getValue());
    
     }
    
     return result;
    
    }
    

Step 3 – Configuring the web.xml

I have to admit, it surprised me to find out that defining the @Path annotation isn’t enough. You also need to do one of two things:

  • Add some magic to the web.xml
  • Create a class that extends javax.ws.rs.Application

Although web.xml is a little out of vogue these days, I chose this option because it meant that I didn’t need to define a custom JAX-RS application. All that would have done is specify the same metadata as I could add to the web.xml file.

To edit the web.xml:

  1. Right-click the project then select Java EE Tools > Generate Deployment Descriptor Stub.
  2. Add the following XML to the WebContext/WEB-INF/web.xml immediately before the element:
    <servlet>
    
    <servlet-name>javax.ws.rs.core.Application</servlet-name>
    
    </servlet>
    
    <servlet-mapping>
    
    <servlet-name>javax.ws.rs.core.Application</servlet-name>
    
    <url-pattern>/rest/*</url-pattern>
    
    </servlet-mapping>
    

Step 4 – Running the application (and fixing it)

  1. Right-click the project then click Run As > Run on server.
  2. Open a web browser at http://localhost:9080/rest/System/properties. You’ll see the following console text:
    [ERROR ] The system could not find a javax.ws.rs.ext.MessageBodyWriter
     or a DataSourceProvider class for the java.util.HashMap type and
     text/html mediaType. Ensure that a javax.ws.rs.ext.MessageBodyWriter
     exists in the JAX-RS application for the type and media type specified.

    This says it couldn’t convert the map to text/html.

  3. To indicate that you want to use JSON, add another annotation. Add the following code to the method to get JSON serialization:
     @GET
    
     @Produces(MediaType.APPLICATION_JSON)
    
     public Map<String, String> getSystemProperties() {
    

    The javax.ws.rs.Produces annotation specifies what type to convert the data to.

  4. This change isn’t reflected automatically so switch to the Servers view, right-click the application, and select Restart.

Welcome to your first working JAX-RS application.

6 comments on"JAX-RS basics"

  1. Edit to my last comment:

    For Step 3, second bullet, after removing web.xml: add the following class. You can choose your own application path value.

  2. Step 2, second bullet, after removing web.xml, add this class: customizate your application path value.

    package p;

    import javax.ws.rs.ApplicationPath;
    import javax.ws.rs.core.Application;

    @ApplicationPath(“/mypath”)
    public class MyApplication extends Application {

    }

  3. Hi Kevin, what incorrect content does the wizard insert? Perhaps there is a bug in here that needs to be addressed?

    This tutorial suggests two ways to get your JAX-RS service up and running. In step 3 above, second bullet point, by using the Application class, it does not necessarily require you to use web.xml. The wizard provides the option to generate the web.xml or not. You can create the web.xml after-the-fact via an action in the Java EE Tools context menu from the project.

  4. Thank you!

    Step 3 – Configuring the web.xml <<< This step is the KEY!

    For the life in me, I couldn't get my REST services up simply because stupid eclipse doesn't create a web.xml file for you by default. And when you use the JAX-RS wizard to update the web.xml, it incorrectly inserts stuff.

  5. it would be useful to also show how to code REST client in Liberty

  6. Sarah Eggleston April 10, 2014

    Thanks for the useful article – I’ve just got my first REST service working!

Join The Discussion

Your email address will not be published. Required fields are marked *