Latest revision as of 10:52, 14 October 2010

Design Specification: JPA RESTful Service

ER 326663

Document History

Project overview

Provide an easy means for users to expose their JPA entities through a RESTful service.

Goals:

• Provide a means for users to implement a standards (JAX-RS/JAXB/JPA) based RESTful service with minimal code.

Proposal:

• The user would implement their JPA based JAX-RS service as follows. They would extend JPASingleKeyResource or JPACompositeKeyResource depending upon their key type.

import javax.ejb.LocalBean;
import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.PersistenceContextType;
import javax.ws.rs.Path;
 
import org.eclipse.persistence.jpa.rest.JPASingleKeyResource;
 
@Stateless
@LocalBean
@Path("/customers")
public class CustomerService extends JPASingleKeyResource<Customer, Long> {
 
    @PersistenceContext(unitName="CustomerService", type=PersistenceContextType.TRANSACTION)
    EntityManager entityManager;
 
    public CustomerService() {
        super(Customer.class);
    }
 
    @Override
    protected EntityManager entityManager() {
        return entityManager;
    }
 
}

Concepts

The following example demonstrates how JAXB and JPA can be used to implement a RESTful (JAX-RS) web service:

• http://wiki.eclipse.org/EclipseLink/Examples/REST/GettingStarted

Requirements

1. Expose JPA EntityManager as RESTful (JAX-RS) service
2. Execute CRUD operations
3. Execute named queries:
   1. read one
   2. read many
   3. update
   4. delete
4. Accept/Return both XML and JSON mime types
5. Convert JPA exceptions into appropriate HTTP response codes

Design Constraints

1. JAX-RS operates on the HTTP protocol, we will be limited by the constraints of this protocol:
   1. URI parameters are limited to simple types
   2. Error conditions are limited to response codes
   3. Operations either produce data or consume data, not both
2. JAX-RS uses JAXB to produce JSON messages (atleast Jersey does). We are limited to the types of JSON messages that can be produced/consumed by JAXB.
3. Collection Property & Type Erasure. Some JAX-RS implementations will not allow use to provide an abstraction for operations that return collections.

Design / Functionality

URI Representation

Data in a RESTful service is referenced through URIs. The common parts of the URI for this example are:

• http://www.example.com/customer-app/rest - the first part of the URI is based on how the application is deployed.
• customers - this part of the path corresponds to the JAX-RS @Path annotation on the RESTful service.

URI for JPA Entities with Unary Key

If the JPA entity has a single part primary key then in the corresponding URI the primary key will be represented as a path parameter. This is a common RESTful operation.

@Entity
public class Customer implements Serializable {
 
    @Id
    private long id;
 
}

URI corresponding to Customer entity with id == 1:

• http://www.example.com/customer-app/rest/customers/1

URI for JPA Entities with Composite Keys

A different mechanism needs be be employed when locating a resource with composite keys. The URI will leverage the property names from the JPA key class as matrix parameters. The advantage of using matrix paramters is that they may be cached. The same representation is also used if composite keys is represented using an embedded key class.

@Entity
@IdClass(CustomerID.clsas)
public class Customer implements Serializable {
 
    @Id
    private long id;
 
    @Id
    private String country;
 
}

public class CustomerID {
 
    private String country;
    private long id;
 
    public CustomerID() {
        super();
    }
 
    public CustomerID(String country, long id) {
        this.country = country;
        this.id = id;
    }
 
    public String getCountry() {
        return country;
    }
 
    public long getId() {
        return id;
    }
 
}

URI corresponding to the instance of Customer with id == 1 and country == CA:

• http://www.example.com/customer-app/rest/customers;id=1;country=CA

Named Queries: Read

A named read query call needs to be mapped to a URI. Below is an example named read query:

@NamedQuery(name = "findCustomerByName",
            query = "SELECT c " +
                    "FROM Customer c " +
                    "WHERE c.firstName = :firstName AND " +
                    "      c.lastName = :lastName")

Get Single Result:

• http://www.example.com/customer-app/rest/customers/singleResult/findCustomerByName;firstName=Jane;lastName=Doe

Get Result List:

• http://www.example.com/customer-app/rest/customers/resultList/findCustomerByName;firstName=Jane;lastName=Doe?firstResult=1&maxResults=10

URI components:

• findCustomersByName - this corresponds to the name of the named query
• singleResult or resultList - this portion indicates whether one or many results are returned
•  ;firstName=Jane;lastName=Doe - these are matrix parameters, the name of the parameter must match exactly the parameter name in the named query.
•  ?firstResult=1&maxResults=10 - optional query parameters to specify firstResult and maxResults

The parameters will be used to build the equivalent of the following:

Query query = entityManager.createNamedQuery("findCustomersByCity");
query.setParameter("firstName", "Jane");
query.setParameter("lastName", "Doe");
query.setFirstResult(1);
query.setMaxResults(10);
return query.getResultList();

Named Queries: Update & Delete

A named update and delete query calls needs to be mapped to URI. Below is an example named update query:

@NamedQuery(name = "updateCustomersByCity",
            query = "UPDATE Customer c " +
                    "SET c.address.city = :newCity " +
                    "WHERE c.address.city = :oldCity")

Execute the Query:

• http://www.example.com/customer-app/rest/customers/execute/updateCustomersByCity;oldCity=Nepean;newCity=Ottawa

URI components:

• updateCustomersByCity - this corresponds to the name of the named query
• execute - this portion indicates the query will be executed
•  ;oldCity=Nepean;newCity=Ottawa- these are matrix parameters, the name of the parameter must match exactly the parameter name in the named query.

The parameters will be used to build the equivalent of the following:

Query query = entityManager.createNamedQuery("updateCustomersByCity");
query.setParameter("oldCity", "Nepean");
query.setParameter("newCity", "Ottawa");
query.executeUpdate();

REST (CRUD) Operations

POST - Create Operation

Using the Jersery client APIs the following is how a post operation is called on our service. The XML message will converted to the appropriate object type using JAXB.

Client c = Client.create();
WebResource resource = client.resource("http://www.example.com/customer-app/rest/customers");
ClientResponse response = resource.type("application/xml").post(ClientResponse.class, "<customer>...</customer>");
System.out.println(response);

This call will be received by

@POST
@Consumes({"application/xml", "application/json"})
public Response create(@Context UriInfo uriInfo, EntityType entity) {
    entityManager().persist(entity);
    UriBuilder uriBuilder = pkUriBuilder(uriInfo.getAbsolutePathBuilder(), entity);
    return Response.created(uriBuilder.build()).build();
}

Successful Responses

• 200 OK
• Return the URI (the representation discussed earlier) for the created entity.

Error Responses:

•  ?

GET - Read Operation

Get is a read-only operation. It is used to query resources. The following is an example of how to invoke a GET call using the Jersey client APIs:

WebResource resource = client.resource("http://www.example.com/customer-app/rest/customers;id=1;country=CA");
ClientResponse response = resource.accept(mimeType).get(ClientResponse.class);

We will need to differentiate between the single key case that uses path parameters and the composite key case that uses matrix parameters:

Single Key - Path Parameter

The unary key parameter will be passed directly to us. Note the String to KeyType conversion will be done using JAXB conversion rules and not JPA conversion rules. There should be no differences for common key types such as Strings and numeric types.

@GET
@Path("{id}")
@Produces({"application/xml", "application/json"})
public EntityType read(@PathParam("id") KeyType id) {
    return entityManager().find(entityClass, id);
}

Composite Key - Matrix Parameters

An instance of the primary key class will need to be derived from the matrix parameters. A utility will need to be provided for this.

@GET
@Produces({"application/xml", "application/json"})
public EntityType read(@Context UriInfo info) {
    return entityManager().find(entityClass, getPrimaryKey(info));
}

Successful Responses

• 200 OK - If a result is returned
• 204 No Content - If no results are returned

Error Responses:

•  ?

PUT - Update Operation

The put operation updates the underlying resource. When using put the client knows the identity of the resource being updated. The following is an example of how to invoke a PUT call using the Jersey client APIs:

Client c = Client.create();
WebResource resource = client.resource("http://www.example.com/customer-app/rest/customers/1");
ClientResponse response = resource.type("application/xml").put(ClientResponse.class, "<customer>...</customer>");
System.out.println(response);

This call will be received by

@PUT
@Consumes({"application/xml", "application/json"})
public void update(EntityType entity) {
    entityManager().merge(entity);
}

Successful Responses

• 200 OK

Error Responses:

• 409 Conflict - Locking related exception

DELETE - Delete Operation

The delete operation is used to remove resources. It is not an error to remove a non-existent resource. Below is an example using the Jersey client APIs:

WebResource resource = client.resource("http://www.example.com/customer-app/rest/customers/1");
ClientResponse response = resource.delete(ClientResponse.class);

We will need to differentiate between the single key case that uses path parameters and the composite key case that uses matrix parameters:

Single Key - Path Parameter

@DELETE
@Path("{id}")
public void delete(@PathParam("id") KeyType id) {
    super.delete(id);
}

Composite Key - Matrix Parameters

An instance of the primary key class will need to be derived from the matrix parameters. A utility will need to be provided for this.

@DELETE
public void delete(@Context UriInfo info) {
    super.delete(getPrimaryKey(info));
}

Successful Responses

• 200 OK

Error Responses:

Matrix Parameters to Instance of ID Class

The matrix parameters could be converted to an ID class in the following manner (Note the code below is currently using query paramters and needs to be updated):

private KeyType getPrimaryKey(UriInfo info) {
    try {
        KeyType pk = (KeyType) PrivilegedAccessHelper.newInstanceFromClass(keyClass);
        for(Entry<String, List<String>> entry : info.getQueryParameters().entrySet()) {
            Field pkField = PrivilegedAccessHelper.getField(keyClass, entry.getKey(), true);
            Object pkValue = ConversionManager.getDefaultManager().convertObject(entry.getValue().get(0), pkField.getType());
            PrivilegedAccessHelper.setValueInField(pkField, pk, pkValue);
        }
        return pk;
    } catch(Exception e) {
        throw new RuntimeException(e);
    }
}

The key class can be obtained using the the JPA metamodel facility:

keyClass = (Class<KeyType>) entityManager().getMetamodel().entity(entityClass).getIdType().getJavaType();

Testing

1. Standalone Testing - In JPA or seperate test framework?
   1. POST (Create)
      1. Test that create is performed
      2. Test that URI returned in response
      3. Test proper error code is returned when an attempt is made to create an existing object.
      4. Test proper error code is returned when an attempt is made to create an entity without pk information.
      5. Test proper error code is returned when an attempt is made to create a null entity
   2. GET (Read)
      1. Test that correct entity is returned
      2. Test that the proper success code is returned when an attempt is made to read an existing entity
      3. Test that the proper success code is returned when an attempt is made to read a non-existant entity with correct pk info
      4. Test that the proper error code is returned when an attempt is made to read an entity with incorrect pk info
         1. To few parameters
         2. To many parameters
         3. Correct number of parameters but value is impropery String format for non-String key parameter
   3. PUT (Update)
      1. Test that update is performed
      2. Test that proper success code is returned when an attempt is made to update an entity
      3. Test that the same update can be made multiple times
      4. Test that proper success code is returned when an attempt is made to update a null entity
      5. Test that proper error code is returned if the update fails
      6. Test that an create is performed if a attempt is made to update a non-existant entity
      7. Test that proper error code is returned if an attempt is made to update an entity with incorrect pk information.
   4. DELETE (Delete)
      1. Test that delete is performed
      2. Test that proper success code is returned when an attempt is made to delete an entity
      3. Test that proper success code is returned when an attempt is made to delete an non-existant entity
      4. Test that the same delete operation can be called multiple times
      5. Test that proper error code is returned if an attempt is made to delete an entity with incorrect pk info (parameter is of wrong type)
   5. Named Queries
      1. Test that query is performed
         1. Read One
         2. Read Many
         3. Update
         4. Delete
      2. Test that proper response code is returned when a successful query is performed
      3. Test that proper error code is returned when an unsuccessful query is performed
      4. Negative Test Cases
         1. When too few parameters are supplied
         2. When too many parameters are supplied
         3. When parameter cannot be converted to appropiate type
         4. When a list of values for a parameter are passed in
2. May want to test with the following JAX-RS Implementations:
   1. Jersey (Reference Implementation)
   2. Apache Wink
   3. JBoss RestEasy

Repository

I propose that this new code live in its own bundle alongside the other JPA bundles:

• trunk
  • jpa
    • org.eclipse.persistence.jpa.rest

Build

• This code requires the JAX-RS public API in order to compile. The necessary CQ has already been filed.
• The build should build this feature into its own bundle.

API

As much shared behaviour as possible with be available in the super class:

package org.eclipse.persistence.jpa.rest;
 
import java.util.List;
import java.util.Map.Entry;
 
import javax.persistence.*;
import javax.ws.rs.*;
import javax.ws.rs.core.*;
 
public abstract class JPAResource<EntityType, KeyType> {
 
    protected Class<EntityType> entityClass;
 
    public JPAResource(Class<EntityType> entityClass) {
        this.entityClass = entityClass;
    }
 
    protected abstract EntityManager entityManager();
 
    @POST
    @Consumes({"application/xml", "application/json"})
    public Response create(@Context UriInfo uriInfo, EntityType entity) {
        ...
    }
 
    @GET
    @Path("singleResult/{namedQuery}")
    @Produces({"application/xml", "application/json"})
    public EntityType namedQuerySingleResult(@Context UriInfo info) {
        ...
    }
 
    protected List<EntityType> namedQueryResultList(@Context UriInfo info) {
        ...
    }
 
    @PUT
    @Consumes({"application/xml", "application/json"})
    public void update(EntityType entity) {
        ...
    }
 
    public void delete(KeyType id) {
    }
 
    protected abstract UriBuilder pkUriBuilder(UriBuilder uriBuilder, EntityType entity);
 
}

A specialized class will be available for a service based on a single key entity:

package org.eclipse.persistence.jpa.rest;
 
import java.lang.reflect.Field;
 
import javax.persistence.metamodel.SingularAttribute;
import javax.ws.rs.*;
import javax.ws.rs.core.UriBuilder;
 
import org.eclipse.persistence.internal.security.PrivilegedAccessHelper;
 
public abstract class JPASingleKeyResource<EntityType, KeyType> extends JPAResource<EntityType, KeyType> {
 
    public JPASingleKeyResource(Class<EntityType> entityClass) {
        super(entityClass);
    }
 
    @GET
    @Path("{id}")
    @Produces({"application/xml", "application/json"})
    public EntityType read(@PathParam("id") KeyType id) {
	...
    }
 
    @DELETE
    @Path("{id}")
    public void delete(@PathParam("id") KeyType id) {
        super.delete(id);
    }
 
    @Override
    protected UriBuilder pkUriBuilder(UriBuilder uriBuilder, EntityType entity) {
	...
    }
 
}

Another specialized class will be available for a service based on a composite key entity:

package org.eclipse.persistence.jpa.rest;
 
import java.lang.reflect.Field;
import java.util.List;
import java.util.Map.Entry;
 
import javax.ws.rs.*;
import javax.ws.rs.core.*;
 
import org.eclipse.persistence.internal.helper.ConversionManager;
import org.eclipse.persistence.internal.security.PrivilegedAccessHelper;
 
public abstract class JPACompositeKeyResource<EntityType, KeyType> extends JPAResource<EntityType, KeyType> {
 
    public JPACompositeKeyResource(Class<EntityType> entityClass) {
	...
    }
 
    @GET
    @Produces({"application/xml", "application/json"})
    public EntityType read(@Context UriInfo info) {
	...
    }
 
    @DELETE
    public void delete(@Context UriInfo info) {
	...
    }
 
    private KeyType getPrimaryKey(UriInfo info) {
	...
    }
 
    @Override
    protected UriBuilder pkUriBuilder(UriBuilder uriBuilder, EntityType entity) {
	...
    }
 
}

GUI

TBD - Tooling could be provided outside of EclipseLink to support this feature.

Config files

This feature does not require the creation of any new configuration files. However the user will be responsible for providing the required JAX-RS, JPA, and JAXB config files.

JAX-RS

• The user will need to create the JAX-RS deployment artifacts appropriate to their deployment platform.

JPA

• The user will need to create the necessary artifacts for JPA

JAXB

• The user will need to create the necessary artifacts for JAXB
  • jaxb.properties file to specify JAXB implementation
  • eclipselink-oxm.xml as an alternate metadata representation

Documentation

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Future Considerations

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.

1. Supporting Atom Links to trim the tree
2. Leveraging HTTP caching