|
|
|
|
|
The examples below provide information on using the REST Auxiliaries for defining Resources.
Implementation Tips
Defining Resource with the REST Auxiliaries can be improved with some useful implementation tips:
Example – Modeling an Instance Resource with Basic Resource Fields
The following example demonstrates modeling a simple instance resource using the BasicResource definition and JAXB annotations:
/**
* {@code BookResource} represents a book from the book store.
*/
@SuppressWarnings("javadoc")
@XmlRootElement(name = "book")
@XmlType(name = "book")
public class BookResource extends BasicResource {
// href field is now inherited from BasicResource
private Long id;
private String title;
private String author;
private Integer count;
/**
* Unique book identifier generated by the book store service. {@code GET}
*/
@XmlElement(name = "id", required = false)
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
/**
* Book title. {@code GET}, {@code PUT}, {@code POST}
*/
@XmlElement(name = "title", required = true)
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
/**
* Book author. {@code GET}, {@code PUT}, {@code POST}
*/
@XmlElement(name = "author", required = true)
public String getAuthor() {
return author;
}
public void setAuthor(String author) {
this.author = author;
}
/**
* Count of such books available in the book store. {@code GET}, {@code PUT}, {@code POST}
*/
@XmlElement(name = "count", required = false)
public Integer getCount() {
return count;
}
public void setCount(Integer count) {
this.count = count;
}
}
A sample transfer of a BookResource representation in JSON using HTTP 1.1 protocol:
GET /demo/bookstore/books/2 HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
HTTP/1.1 200 OK
Content-Type: application/json
{
"href": "/demo/bookstore/books/2",
"id": 2,
"title": "Refactoring: Improving the Design of Existing Code",
"author": "Martin Fowler",
"count": 5
}
Example – Modeling a Collection Resource with Paging Support
The following example demonstrates modeling a simple collection resource using the PaginatedCollectionResource definition and JAXB annotations:
/**
* {@code BookCollectionResource} represents a collection of books. The resource holds a collection of
* {@link BookResource} entries and the common fields of collection resources which support pagination. Paging may be
* defined via {@link HttpHeaders#RANGE} and {@link HttpHeaders#CONTENT_RANGE} headers or via
* {@link QueryParameters#OFFSET} and {@link QueryParameters#LIMIT} query parameters.
*/
@SuppressWarnings("javadoc")
@XmlRootElement(name = "books")
@XmlType(name = "books")
public class BookCollectionResource extends PaginatedCollectionResource {
// href field is now inherited from {{BasicResource}}
// offset, limit, previous, next, last first are now inherider from {{PaginatedCollectionResource}}
private Collection<BookResource> entries;
/**
* Collection of {@link BookResource} representations that satisfy the filtering and limitation constraints given as
* query parameters. In case there are no books to satisfy the constraints then this field is omitted. {@code GET}
*/
@XmlElement(name = "entries", required = false)
public Collection<BookResource> getEntries() {
return entries;
}
public void setEntries(Collection<BookResource> entries) {
this.entries = entries;
}
}
Example – Modeling a Resource using Discovery Links
The following example demonstrates modeling a simple resource containing discovery information using DiscoveryLink:
/**
* The base M2M resource contains links to the main RESTful services provided by the system. Clients that wish to be
* decoupled from the exact outline of the URIs may obtain the base resource and take advantage of the links for
* discovery of the RESTful services of interest.
*/
@SuppressWarnings("javadoc")
@XmlType(name = "m2m")
@XmlRootElement(name = "m2m")
public class M2MResource extends BasicResource {
private DiscoveryLink dm;
private DiscoveryLink gm;
private DiscoveryLink fim;
/**
* Link to the device management services for discovery and management of connected devices and corresponding
* protocols and adapters registered on the system. {@code GET}
*/
@XmlElement(name = "dm", required = false)
public DiscoveryLink getDm() {
return dm;
}
public void setDm(DiscoveryLink dm) {
this.dm = dm;
}
/**
* Link to the groups management services for discovery and management of groups and group providers registered on the
* system. {@code GET}
*/
@XmlElement(name = "gm", required = false)
public DiscoveryLink getGm() {
return gm;
}
public void setGm(DiscoveryLink gm) {
this.gm = gm;
}
/**
* Link to the functional items management services for discovery and management of functional items and their
* properties and operations. {@code GET}
*/
@XmlElement(name = "fim", required = false)
public DiscoveryLink getFim() {
return fim;
}
public void setFim(DiscoveryLink fim) {
this.fim = fim;
}
...
}
A sample transfer of a M2MResource representation in JSON using HTTP 1.1 protocol:
GET /m2m HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
HTTP/1.1 200 OK
Content-Type: application/json
{
"href": "/m2m",
"dm": {
"href": "/m2m/dm",
"method": "GET",
"description": "Locates device management services for discovery and management of connected devices
and corresponding protocols and adapters registered on the system"
},
"gm": {
"href": "/m2m/gm",
"method": "GET",
"description": "Locates groups management services for discovery and management of groups
and group providers registered on the system."
},
"fim": {
"href": "/m2m/fim",
"method": "GET",
"description": "Locates functional items management services for discovery and management
of functional items and their properties and operations"
}
}