Revision as of 11:53, 30 September 2010

Design Specification: JPA RESTful Service

ER 326663

Document History

Project overview

Overview of the project/feature. Why is it desired, what are its goals.

Goals:

• goal 1
• goal 2

Concepts

The following example demonstrates how JPA can be used to implement a RESTful web service:

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

Requirements

The following sections will expand the goals of this project into more concrete requirements.

Design Constraints

Design / Functionality

URI Representation

Data in a RESTful service is referenced through URIs.

Unary Key

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

Composite Keys

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

Named Queries

@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/findCustomerByName/singleResult?firstName=Jane&lastName=Doe

Get Result List:

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

REST (CRUD) Operations

POST - Create Operation

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

GET - Read Operation

Get is a read-only operation. It is used to query resources.

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

PUT - Update Operation

The put operation updates the underlying resource. When using put the client knows the identity of the resource being updated.

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

DELETE - Delete Operation

The delete operation is used to remove resources. It is not an error to remove a non-existent resource.

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

Testing

API

GUI

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.