Module Description

Feature Set

The REST module provides the following features and functionalities:

• Support for exposing JAX-RS 1.x and JAX-RS 2.0 compliant RESTful web services in OSGi via integration of Jersey 2.22 JAX-RS RESTful container and OSGi JAX-RS Connector 5.0 publisher;
• Support for controlling the access to resources exposed via RESTful web services via a global ContainerRequestFilter which configures a policy-based implementation of SecurityContext for all requests processed by the Jersey JAX-RS container;
• Support for transferring resource representations using JSON serialization format via integration of Jackson 2.8.9 JAX-RS provider or Gson 2.8.0 JSON provider, with both supporting typed and untyped serialization and deserialization, furthermore they can be configured to be unified in terms of the REST API;
• Auxiliary classes, utilities and resource definitions to ease development of RESTful web services conforming to the common behaviors and definitions;
• Support for subscribing for remote events and receiving notifications via long polling in a RESTful manner;
• Support for subscribing for remote events and receiving notifications via web sockets using osgi.events-legacy or osgi.events.v1-text sub-protocols;
• Support for controlling the access to events based on integration with Policy Admin;
• Support for runtime visualization of Swagger 1.2 compliant REST API documentation and invocation of REST API operations through Swagger's web interface;

Known Issues and Limitations

The REST module has the following limitations:

• When the Gson JSON provider is used with untyped values (for example in a Map), the provider converts Integers to Doubles. For example an Integer value of 4 would get converted to a Double value of 4.0.
• When @FormDataParam annotation is used, the behavior of the REST module becomes unstable.

Module Dependencies

All components of the RESTful Web Services module run within the OSGi Framework and use basic OSGi packages and services provided by Core module (OSGi Core including  extensions) and OSGi modules (OSGi Compendium including extensions). The components which enable security for RESTful web services and remote events rely on integration with Policy Admin module. The components for remote events support via web sockets depend on the OSGi remote events web socket application which is provided by the Websockets module.

Third Party

The RESTful Web Services module depends on certain javax* and org* packages that may not be available in the Java execution environment, thus all required javax.xml.bind*, org.xml*, org.w3c*, javax.ws.rs*, javax.annotation*, javax.activation*, javax.servlet* packages that are defined within a certain JSR are packed as OSGi bundles and provided by the Externals module. All packages are imported and exported without specifying a version – version reasoning is based on OSGi contracts. A set of contracts for the JSR specifications are defined by the OSGi Alliance in the Portable Java Contract Definitions document. The contracts defined are versioned according to the corresponding JSR specification version. Bundles in RESTful Web Services module act as clients of contracts and import the packages required with no version and express a dependency on the OSGi contract that defines the packages and the exact specification version required. Bundles in  Externals module act as providers of contracts and express every version of the contract they support. Consequently, the client bundle is only tied to the specification version and each provider of the contract is free to continue using their chosen versioning strategy.

The RESTful Web Services module depends on the following contract providers from the Externals module:

•     xml-apis.jar – provides JavaJAXP, version 1.4 (Additional Bundles)
•     javax.annotation.jar – provides JavaAnnotation, version 1.2 (JAVAX Support Bundles)
•     javax.activation.jar – provides JavaBeanActivation, version 1.1 (JAVAX Support Bundles) or
•     javax.activation.compact.jar – provides JavaBeanActivation, version 1.1 (JAVAX Support Bundles) for the compact version container
•     javax.inject.jar – provides JavaInject, version 1.0 (JAVAX Support Bundles)
•     javax.validation.jar – provides JavaBeanValidation, version 1.1.0 (JAVAX Support Bundles)
•     javax.xml.bind.jar – provides JavaJAXB, version 2.1 (JAVAX Support Bundles) or
•     javax.xml.bind.compact.jar – provides JavaJAXB, version 2.1 (JAVAX Support Bundles) for the compact version container

    The RESTful Web Services module depends on the following additional bundles from the Externals module:

•     javax.servlet.jar
•     org.json.jar

The REST container does not use boot delegation for the required classes, if they are provided by the Externals bundles, for the following packages:

•   javax.annotation
•   javax.activation
•   javax.xml.bind

If they are provided with the JVM, the REST container uses boot delegation.

Licensing Information

•   Check Third-Party Licenses: REST Services.