Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/DesignDocs/326663
Design Specification: JPA RESTful Service
Document History
Date | Author | Version Description & Notes |
---|---|---|
2010/09/30 | Blaise Doughan | Initial Version |
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:
Requirements
- Expose JPA EntityManager as RESTful (JAX-RS) service
- Execute CRUD operations
- Excute named queries
- Accept both XML and JSON mime types
Design Constraints
- JAX-RS operates on the HTTP protocol, we will be limited by the constraints of this protocol.
- URI parameters are limited to simple types
Design / Functionality
URI Representation
Data in a RESTful service is referenced through URIs.
The common parts of the URI 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 service.
Unary Key
Composite Keys
Named Queries
A named query call needs to be mapped to a URI. Below is an example named query:
@NamedQuery(name = "findCustomerByName", query = "SELECT c " + "FROM Customer c " + "WHERE c.firstName = :firstName AND " + " c.lastName = :lastName")
Get Single Result:
Get Result List:
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 the query parameters, the name of the parameter must match exactly the parameter name in the named query.
REST (CRUD) Operations
POST - Create Operation
@POST @Consumes(MediaType.APPLICATION_XML) public void create(Customer customer) { entityManager.persist(customer); }
Successful Responses
- 200 OK
Error Responses:
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); }
Possible Errors:
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); }
Possible Errors:
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); } }
Possible Errors:
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.
Issue # | Owner | Description / Notes |
---|---|---|
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.
Issue # | Description / Notes | Decision |
---|---|---|
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.