Creating a RESTful Web Service - Part 4/5

Java API for RESTful Web Services (JAX-RS) is the Java EE standard for creating RESTful Web Services.  In this post we will create a RESTful service from an EJB session bean using JAX-RS.

• Part 1 - The Database
• Part 2 - Mapping the Database to JPA Entities
• Annotations
• XML Metadata
• Part 3 - Mapping JPA entities to XML (using JAXB)
• Part 4 - The RESTful Service
• Part 5 - The Client

Customer Service

We will use the @PersistenceContent annotation to inject an EntityManager onto our EJB session bean.  We will use this EntityManager to perform all of our persistence operations.  Back in part 2 we configured our persistence unit to use the Java Transaction API  (JTA), so we will not need to do any of our own transaction handling.

You can see below how little JPA code is required to implement our RESTful service.  Of course to make this production quality service we will need to include response objects and exception handling.  In future posts I'll cover these topics in detail.  For the purpose of this example the following is all the code you need to run your service.

package org.example;

import java.util.List;

import javax.ejb.LocalBean;
import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.PersistenceContextType;
import javax.persistence.Query;
import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Stateless
@LocalBean
@Path("/customers")
public class CustomerService {

    @PersistenceContext(unitName="CustomerService", 
                        type=PersistenceContextType.TRANSACTION)
    EntityManager entityManager;

    @POST
    @Consumes(MediaType.APPLICATION_XML)
    public void create(Customer customer) {
        entityManager.persist(customer);
    }

    @GET
    @Produces(MediaType.APPLICATION_XML)
    @Path("{id}")
    public Customer read(@PathParam("id") long id) {
        return entityManager.find(Customer.class, id);
    }

    @PUT
    @Consumes(MediaType.APPLICATION_XML)
    public void update(Customer customer) {
        entityManager.merge(customer);
    }

    @DELETE
    @Path("{id}")
    public void delete(@PathParam("id") long id) {
        Customer customer = read(id);
        if(null != customer) {
            entityManager.remove(customer);
        }
    }

    @GET
    @Produces(MediaType.APPLICATION_XML)
    @Path("findCustomersByCity/{city}")
    public List<Customer> findCustomersByCity(@PathParam("city") String city) {
        Query query = entityManager.createNamedQuery("findCustomersByCity");
        query.setParameter("city", city);
        return query.getResultList();
    }

}

WEB-INF/web.xml

In the WEB-INF/web.xml file we need to configure three things:

1. Start the Jersey service for our application.  We will use the Jersey implmenation of JAX-RS, it is included in the version of GlassFish we are using for this example.
2. You interact with JAX-RS through URIs.  We need to tell Jersey which URLs (a URL is a type of URI) relate our service.  In our web context URLs starting with "rest" correspond to our RESTful service.
3. We need to make our JPA persistence context we created in part 3 available for use by our EJB session bean.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    <servlet>
        <servlet-name>Jersey Web Application</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Jersey Web Application</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>
    <persistence-context-ref>
        <persistence-context-ref-name>persistence/em</persistence-context-ref-name>
        <persistence-unit-name>CustomerService</persistence-unit-name>
    </persistence-context-ref>
</web-app>

Packaging/Deployment

We will package up everying in a WAR file.  The JAR file containing the contents we created in part 2 and part 3 should be inluded in the war in the directory WEB-INF/lib.

CustomerService.war

• WEB-INF
• lib
• CustomerService.jar
• org
• example
• Customer.class
• Address.class
• PhoneNumber.class
• jaxb.properties
• META-INF
• MANIFEST.MF
• persistence.xml
• classes
• org
• example
• CustomerService.class
• web.xml
• META-INF
• MANIFEST.MF

Next Steps

In the next post we'll look at creating a client for our RESTful service.

• Part 1 - The Database
• Part 2 - Mapping the Database to JPA Entities
• Annotations
• XML Metadata
• Part 3 - Mapping JPA entities to XML (using JAXB)
• Part 4 - The RESTful Service
• Part 5 - The Client 

Further Reading

If you enjoyed this post you may also be interested in:

• RESTful Services
• MOXy's XML Metadata in a JAX-RS Service
• MOXy as Your JAX-RS JSON Provider - Server Side  
• MOXy as Your JAX-RS JSON Provider - Client Side
•  Application Server Integration
• GlassFish 3.1.2 is Full of MOXy (EclipseLink JAXB)
• EclipseLink MOXy is the JAXB Provider in WebLogic Server 12c