Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/DesignDocs/326663"
m (→GET - Read Operation) |
|||
Line 1: | Line 1: | ||
− | <div style=" | + | <div style="border-right: #000000 1px solid; padding-right: 5px; border-top: #000000 1px solid; padding-left: 5px; float: right; padding-bottom: 5px; margin: 5px; border-left: #000000 1px solid; padding-top: 5px; border-bottom: #000000 1px solid">__TOC__</div> |
− | = Design Specification: JPA RESTful Service = | + | = Design Specification: JPA RESTful Service = |
− | [http://bugs.eclipse.org/326663 ER 326663] | + | [http://bugs.eclipse.org/326663 ER 326663] |
− | == Document History == | + | == Document History == |
− | {| | + | |
− | |- | + | {| class="FCK__ShowTableBorders" |
− | ! Date | + | |- |
− | ! Author | + | ! Date |
− | ! Version Description & Notes | + | ! Author |
− | |- | + | ! Version Description & Notes |
+ | |- | ||
| | | | ||
| | | | ||
Line 16: | Line 17: | ||
|} | |} | ||
− | == Project overview == | + | == Project overview == |
− | Overview of the project/feature. | + | Overview of the project/feature. Why is it desired, what are its goals. |
− | 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 | + | == Design Constraints == |
− | == | + | == Design / Functionality == |
− | ==== POST - Create Operation ==== | + | === 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 ==== | ||
+ | |||
+ | <source lang="java"> | ||
+ | @NamedQuery(name = "findCustomerByName", | ||
+ | query = "SELECT c " + | ||
+ | "FROM Customer c " + | ||
+ | "WHERE c.firstName = :firstName AND " + | ||
+ | " c.lastName = :lastName") | ||
+ | </source> | ||
+ | |||
+ | |||
+ | *http://localhost/customers/findCustomerByName/'''singleResult'''?'''firstName'''=Jane&'''lastName'''=Doe | ||
+ | *http://localhost/customers/findCustomerByName/'''resultList'''?first'''Name'''=Jane&'''lastName'''=Doe<br> | ||
+ | |||
+ | === REST (CRUD) Operations === | ||
+ | |||
+ | ==== POST - Create Operation ==== | ||
<source lang="java"> | <source lang="java"> | ||
Line 46: | Line 74: | ||
@Consumes(MediaType.APPLICATION_XML) | @Consumes(MediaType.APPLICATION_XML) | ||
public void create(Customer customer) { | public void create(Customer customer) { | ||
− | + | entityManager.persist(customer); | |
} | } | ||
− | </source> | + | </source> |
− | ==== GET - Read Operation ==== | + | ==== GET - Read Operation ==== |
− | Get is a read-only operation. | + | Get is a read-only operation. It is used to query resources. |
<source lang="java"> | <source lang="java"> | ||
Line 59: | Line 87: | ||
@Path("{id}") | @Path("{id}") | ||
public Customer read(@PathParam("id") long id) { | public Customer read(@PathParam("id") long id) { | ||
− | + | return entityManager.find(Customer.class, id); | |
} | } | ||
− | </source> | + | </source> |
− | ==== PUT - Update Operation ==== | + | ==== PUT - Update Operation ==== |
− | The put operation updates the underlying resource. | + | The put operation updates the underlying resource. When using put the client knows the identity of the resource being updated. |
<source lang="java"> | <source lang="java"> | ||
Line 71: | Line 99: | ||
@Consumes(MediaType.APPLICATION_XML) | @Consumes(MediaType.APPLICATION_XML) | ||
public void update(Customer customer) { | public void update(Customer customer) { | ||
− | + | entityManager.merge(customer); | |
} | } | ||
− | </source> | + | </source> |
− | ==== DELETE - Delete Operation ==== | + | ==== DELETE - Delete Operation ==== |
− | The delete operation is used to remove resources. | + | The delete operation is used to remove resources. It is not an error to remove a non-existent resource. |
<source lang="java"> | <source lang="java"> | ||
Line 83: | Line 111: | ||
@Path("{id}") | @Path("{id}") | ||
public void delete(@PathParam("id") long id) { | public void delete(@PathParam("id") long id) { | ||
− | + | Customer customer = read(id); | |
− | + | if (null != customer) { | |
− | + | entityManager.remove(customer); | |
− | + | } | |
} | } | ||
− | </source> | + | </source> |
− | == | + | == Testing == |
− | == | + | == API == |
− | == | + | == GUI == |
− | == | + | == Config files == |
− | == | + | == 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. | |
− | + | {| class="FCK__ShowTableBorders" | |
− | + | |- | |
− | + | ! Issue # | |
− | + | ! Owner | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | {| | + | |
− | |- | + | |
− | ! Issue # | + | |
− | ! Owner | + | |
! Description / Notes | ! Description / Notes | ||
− | |- | + | |- |
− | | | + | | |
− | | | + | | |
− | | | + | | |
|} | |} | ||
− | == Decisions == | + | == 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. | + | This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important. |
− | {| | + | {| class="FCK__ShowTableBorders" |
− | |- | + | |- |
− | ! Issue # | + | ! Issue # |
− | ! Description / Notes | + | ! Description / Notes |
! Decision | ! Decision | ||
− | |- | + | |- |
− | | | + | | |
− | | | + | | |
− | | | + | | |
|} | |} | ||
− | == Future Considerations == | + | == 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. | 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. |
Revision as of 11:37, 30 September 2010
Design Specification: JPA RESTful Service
Document History
Date | Author | Version Description & Notes |
---|---|---|
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
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
Composite Keys
Named Queries
@NamedQuery(name = "findCustomerByName", query = "SELECT c " + "FROM Customer c " + "WHERE c.firstName = :firstName AND " + " c.lastName = :lastName")
- http://localhost/customers/findCustomerByName/singleResult?firstName=Jane&lastName=Doe
- http://localhost/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
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.