Overview

This document elaborates the main auxiliaries intended to ease development of RESTful Web Services conforming to the common behaviors and definitions. Defined are the main utilities and common resource definitions which enable resource representation customization, collection resource pagination, error handling, accessing available JAX-RS providers registered in the system, consuming RESTful web services and web socket messages and generating and browsing documentation for RESTful web APIs.

Defining Resources

Auxiliary classes and resource definitions are provided to ease implementation of resource identification and filtering, resource linking and resource link expansion while developing RESTful web services. The main resource class and field type definitions are displayed below. Those classes represent the basic types of resources and resource fields such as basic and identifiable resource definitions, discovery links and expandable links definitions.

Those classes and resource definitions are exported via the com.prosyst.mbs.services.rest and com.prosyst.mbs.services.rest.link packages and reflect the common behaviors and definitions elaborated in URI Space and Resource Representations from Common Behaviors and Definitions  guide for RESTful Web Services. For examples refer to Defining Resources Using the REST Auxiliaries guide.

BasicResource

Abstract class that should be inherited by all instance and collection resources in the system. It defines the mandatory self link field href that must be included in all resource representations retrieved from the system.

IdentifiableResource

Abstract class that extends BasicResource and should be inherited by all instance resources which represent an identifiable entity in the system. It defines several identification fields – id, gatewayId, name, tags,that should be included in all resource representations transferred within the system.

PaginatedCollectionResource

This class holds the common fields of collection resources which support:

• pagination:
  • offset
  • limit
• navigational links:
  • first
  • last
  • previous
  • next

Paging may be defined via Range and Content-Range headers or via offset and limit query parameters. Regardless of the approached used by the client to limit the collection of resources retrieved, the resources that represent collections shall conform to some common schema enabling pagination by including offset and limit fields and navigational links to ease the traversing the returned subset of resources. For more details refer to Paging for Collection Resources guide.

DiscoveryLink

Discovery links represent hyper media links with embedded meta data that can be used for resource discovery. The The discovery links always contain a href field holding a reference to the linked resource and may optionally contain a description field holding textual description of the linked resource and/or a method field specifying the HTTP method that needs to be used against the link.

ExpandableLink

Expandable hyper media links represent hyper media links that can be expanded with the fields of the resources that they refer to. The expandable links always contain a href field holding a reference to the linked resource and id field holding the unique identifier of the entity that is represented by this resource. Various additional fields may be included depending on the representation of the linked resource end the link expansion constraints.

Defining Error Responses

Auxiliary classes and resource definitions are provided to ease implementation of error handling while developing RESTful web services. The main resource classes and utilities are displayed below. Those classes include error resource definition, general error codes and utilities to create various error responses containing error descriptions.

Those classes and resource definitions are exported via the com.prosyst.mbs.services.rest.error package and reflect the common behaviors and definitions elaborated in the Error Handling section of Versioning and Error Handling guide from the Common Behaviors and Definitions for RESTful Web Services.Examples are provided in the Defining Error Responses Using the REST Auxiliaries guide.

ErrorDescription

Successful requests will generally return an HTTP status code of 200 (OK), 201 (Created), 202(Accepted), 204 (No Content), or 303 (See Other) to indicate that the requested action has been successfully performed. In addition, they might include a response message body (with an appropriate media type) containing a representation of the requested resources. If a response is returned with an error status code (400-499 for client error, 500-599 for server error) then the server should also return a response message body containing an error representation further describing the cause of the problem.

ExceptionDescription

This class represents information for the exception, in case this error message is generated due to the underlying service implementation throwing an exception.

ErrorDescriptionUtils

ErrorDescriptionUtils provides convenient utility methods to create various ErrorDescription objects as well as wrap them in HTTP response or {{WebApplicationException}} objects depending on the implementation use cases and needs.

GeneralErrorCodes

GeneralErrorCodes provides application error codes that provide further categorization and identification for some general problems and errors that may be encountered by a particular RESTful web service, thus are purposed for use in the ErrorDescription representations that should be provided in responses that contain HTTP error status codes.

Customizing Resource Representations

Auxiliary classes and utilities are provided to ease accessing request contextual information and parsing the values of the most commonly used query parameters and HTTP headers while developing RESTful web services:

• utilities to ease working with injectable interfaces providing contextual information for the requests;
• utilities to easily extract and parse the most commonly used query parameters and HTTP request headers from the contextual information for the request;
• utilities to easily extract and parse the resource field exclusion/inclusion and hypermedia link expansion expressions and ease implementation of representation constraints application and resource representation customization.

Those auxiliaries are exported via the com.prosyst.mbs.services.rest.util.context package and reflect the common behaviors and definitions elaborated in Customizing Resource Representations from Common Behaviors and Definitions for RESTful Web Services guide. Examples are provided in Customizing Resource Representations Using the REST Auxiliaries guide.

RequestContextUtils

RequestContextUtils provides utility methods for convenient processing of information about the context of the request which is being dispatched to the corresponding JAX-RS method. JAX-RS resources which depend on contextual information can handle javax.ws.rs.core.HttpHeaders, javax.ws.rs.core.UriInfo or javax.servlet.HttpServletRequest injectable interfaces easily by using this utility.

RepresentationConstaints

RepresentationConstraints encapsulates various resource representation constraints. The class provides methods for obtaining and initializing RepresentationConstraints objects based on the request context information - javax.ws.rs.core.HttpHeaders, javax.ws.rs.core.UriInfo or javax.servlet.HttpServletRequest, checking the representation constraints defined over a certain field, providing String representation of the constraints and recursive access to the nested and enclosing representation constraints of embedded resources. Object pooling is used for obtaining necessary RepresentationConstraints objects, thus it is recommended that the objects are released when no longer needed.

Paging for Collection Resources

Auxiliary classes and utilities are provided to ease defining of collection resources which support paging and implementing pagination in the context of a stateless server:

• paginated collection resource definition and utilities to ease implementation of resource pagination for collection resources
• paging service is provided which associates unique identifiers to collection page accessors encapsulating a shallow copy of the collection for pagination, thus paging forth and back through the collection resource remains consistent and resistant to changes that may occur in the underlying collection in time.

Those auxiliaries are exported via the com.prosyst.mbs.services.rest.pagination package and reflect the common behaviors and definitions elaborated in Limiting Query Results and Pagination from Common Behaviors and Definitions for RESTful Web Services. For examples refer to Paging for Collection Resources Using the REST Auxiliaries guide.

PaginatedCollectionResource

This class holds the common fields of collection resources which support pagination - offset, limit, and navigational links first, last, previous and next. Paging may be defined via Range and Content-Range headers or via offset and limit query parameters. Regardless of the approached used by the client to limit the collection of resources retrieved, the resources that represent collections shall conform to some common schema enabling pagination by including offset and limit fields and navigational links to ease the traversing the returned subset of resources.

CollectionPageService

CollectionPageService provides means to ease development of RESTful web services that wish to take advantage of collection resource pagination. The service associates unique identifiers (generally derived from the HTTP session identifier and the request URI) to {{CollectionPageAccessor}}s instances encapsulating a shallow copy of the collection for pagination, thus paging forth and back through the collection resource remains consistent and resistant to changes that may occur in the underlying collection in time. Certain parameters of the service are configurable via an OSGi configuration - maximum age of an accessor (time to cache an iterator), maximum count of cached accessors, whether to refresh the age of an accessor when it is looked up through the service or not.

CollectionPageAccessor

CollectionPageAccessor encapsulates a shallow copy of a collection of elements of type E to which pagination will be applied. The CollectionPageAccessor enables collection resource pagination by providing random access to subsets of the collection's elements (page) based on a given offset and limit. The collection of elements retrieved from the page can then be used for creating PaginatedCollectionResource instances based on the RESTful web service logic. Paging forth and back through the collection resource remains consistent and resistant to changes that may occur in the underlying collection in time.

The dynamic nature of the OSGi environment implies that classes provided by bundles my be loaded and unloaded at any time due to execution of certain bundle operation, thus caching collections with bundle-provided element types may lead to class loading and unloading problems and type mismatches. To prevent such problems it is recommended that applications cache collections which elements types are provided by the standard Java library. If such restriction is not applicable, then the applications must take care for explicitly removing CollectionPageAccessor instances which are assumed containing illegal or obsolete elements.

CollectionPage

CollectionPage subclasses java.util.Collection and encapsulates a collection of elements of type {{E}} representing a single page of the collection for pagination based on a specified offset and limit.

PaginationUtils

PaginationUtils provides common methods to ease development of REST web services which employ pagination of collection resources which are represented as PaginatedCollectionResource. This class holds utility methods for calculating the pages while navigating through the collection and filling the offset, limit and navigation links for collection resource pages.

Accessing Registered JAX-RS Providers

Auxiliary classes and utilities are provided which allow access to the JAX-RS providers registered in the system, including JAX-RS providers prioritization functionality based on the same mechanisms for discovery and prioritization of JAX-RS providers implemented in the JAX-RS RESTful container. Those utilities can be used to easily configure the available JAX-RS providers for a client and reflect the dynamic changes implied by OSGi without the need to rebuild the client. Another useful application of this utility is implementing some asynchronous serialization/deserialization which is not in the context of a request or the implementation class in not exposed to the JAX-RS container, thus the Providers injectable dependency cannot be used.

Those auxiliaries are exported via the com.prosyst.mbs.services.rest.util.providers package. For examples refer to the A guide.

ProvidersAccessor

ProvidersAccessor represents an extension of the javax.ws.rs.ext.Providers injectable interface which provides means for accessing the JAX-RS providers that are currently available in the system outside the context of a request. ProvidersAccessor instances encapsulate the JAX-RS providers tracking and prioritizing mechanisms implemented in the JAX-RS container and provide functionality for retrieving the most prioritized javax.ws.rs.ext.MessageBodyReader -s and javax.ws.rs.ext.MessageBodyWriter -s.

ProvidersAccessorFacotry

ProvidersAccessorFactory represents a factory for creating ProvidersAccessor instances which encapsulate the JAX-RS providers tracking and prioritizing mechanisms implemented in the JAX-RS container. The factory method requires a{{BundleContext}} which is used for tracking and getting the JAX-RS providers which are registered as services in the OSGi runtime. If the Java Runtime Environment supports permissions then the bundle associated with the provided BundleContext must have the appropriate ServicePermission to get the JAX-RS provider services using at least one of the named classes under which the services are registered.

ProvidersAccessorImpl, ComparableMessageBodyReader and ComparableMessageBodyWriter

Nested in the ProvidersAccessorFacotry class is the default implementation of the ProvidersAccessor interface. It tracks javax.ws.rs.ext.MessageBodyReader and javax.ws.rs.ext.MessageBodyWriter services and wraps them in the comparable ComparableMessageBodyReader and ComparableMessageBodyWriter respectively which for the purposes of JAX-RS providers prioritization.

Glassfish Jersey REST Java Client Extensions

Java REST client API based on Jersey 2.22 JAX-RS Client API is provided for configuring and building a JAX-RS 2.0 compliant REST client and creating target resources using configured schema, host, port, default HTTP headers for each request, resource serialization and deserialization is delegated to the JAX-RS providers available in the system. The Bosch Jersey REST client extension makes privileged calls to the underlying third party library, thus, no permissions are checked for the callers in case security is enabled.

The Jersey REST client extension classes are exported via the com.prosyst.mbs.services.rest.client.jersey package, they are purposed for development of automated tests for RESTful web services. For examples, please see the

SecureClientBuilder

RESTClientBuilder provides a convenient way to instantiate and configure a Client instance following the Java builder design pattern. The builder uses some default settings for the schema, host and port in case they are not provided by the user. Client instances which are built using this builder wrap the default Jersey implementation providing privileged execution of the interface methods, serialization and deserialization of resources are delegated to the currently available JAX-RS providers which has been registered as OSGi services.

Eclipse Jetty Java Web Socket Client Extension

Java web socket client API based on is provided for configuring and building a Web Socket client and opening web sockets using configured schema, host, port, default HTTP headers for each request, resource serialization and deserialization is delegated to the JAX-RS providers available in the system. The Bosch web socket client extension makes privileged calls to the underlying third party library, thus, no permissions are checked for the callers in case security is enabled.

The Eclipse Jetty Java web socket client extension classes are exported via the com.prosyst.mbs.services.rest.client.jetty package, they are purposed for development of automated tests for RESTful web services. For examples, please see the guide.

WebSocketClientBuilder

WebSocketClientBuilder provides a convenient way to instantiate and configure a WebSocketClient instance following the Java builder design pattern. The builder uses some default settings for the schema, host and port in case they are not provided by the user. WebSocketClient instances which are built using this builder delegate deserialization of web socket messages to the currently available JAX-RS providers via the ProvidersAccess utility.

WebSocketClient

WebSocketClient represents a client to be used for the purposes for automated functional tests for web sockets. This class provides functionality for opening websockets by specifying URIs using pre-configured schema, host, port, default HTTP headers for each request. An instance of this class can be configured and built using the WebSocketClientBuilder utility class.

MessageSource

An instance of the MessageSource can be obtained from the WebSocketClient. This utility class encapsulates logic for managing single web socket connection - provides functionality for connection via socket, adding message listeners and closing the client socket, notifies registered MessageListener -s each time a message is being received via the web socket.

WebSocketListener, MessageListener and Message

WebSocketListener listens for for web socket events using the Jetty web socket annotations defined in the org.eclipse.jetty.websocket.api.annotations package. This class has functionality which supports adding, removing and notifying of multiple {[MessageListener}} -s on the occurrence of web socket events. MessageListener provides notification for opening and closing of a web socket connection, as well as receiving messages. Received web socket messages are wrapped up in Message objects, so they could easily be extracted and deserialized using the available JAX-RS providers.