About the REST Binding Component

The REST Binding Component provides external connectivity for REST over HTTP, allowing external systems to call RESTful web services hosted by the JBI platform and allowing JBI components to call external web services. Binding components implement the protocol transformations between abstract messages handled by the JBI Service Engines and concrete messages of the protocol. Other JBI components, such as the BPEL Service Engine, can leverage the REST Binding Component to provide and consume RESTful web services.

The REST Binding Component is based on Jersey 1.0.3.1, which implements the JSR-311 project for JAX-RS (Java API for RESTful Web Services). Jersey provides APIs for extending functionality, a client API for REST, an API for JSON support, and an API for using JAXB with JSON. It also supports annotations defined in JSR-311.

Using REST, data and functionality are resources that are accessed through Uniform Resource Identifiers (URIs), which are usually web links. Each discrete resource is identified by a unique URI. The REST Binding Component uses a simple subset of HTTP operations to transfer and transform the data represented by the resources. The data can be of various formats, including plain text, XML, HTML, JSON, and so on.

The REST BC allows you to specify custom HTTP headers and path parameters where needed. Headers define certain traits of the data being processed, including metadata, application state information, and so on. Metadata includes information about the resource, such as the accepted format and content type. The REST BC performs transformation logic based on the HTTP headers. Path parameters can be either query or matrix in style. Query parameters defined attributes of the whole URI, while matrix parameters only modify segments of the URI.

The transformation of abstract messages to REST messages occurs in the REST Binding Component. WSDL extensibility elements are used to configure this transformation. The WSDL extensibility elements are part of the binding and service sections of WSDL documents. Both the binding and service sections of a WSDL document must be properly configured to determine how the message is transformed and the destination of that message.

REST Binding Component Features

The REST BC provides the following features and functionality to GlassFish ESB:

• Gives GlassFish ESB applications the ability to provision and consume RESTful web services.

• Provides easy configuration through a wizard that guides you through the steps of creating a REST WSDL document.

• Allows you to dynamically set HTTP headers and parameters using normalized message properties in a BPEL process.

• Allows you to define application variables and configurations so you can port your REST applications from one environment to another.

• Supports substitution variables in URLs which can be populated from normalized message properties in the BPEL process or from application variables.

• Supports GET, PUT, POST, DELETE, and HEAD HTTP methods.

• Supports XML, JSON, and plain text content types.

• Supports Secure Sockets Layer (SSL).

• Supports Jersey client filters, so you can modify a REST request or response for an outbound REST client interaction.

Supported HTTP Methods

The REST BC supports a subset of HTTP methods to manipulate the requests and responses processed by GlassFish ESB. Certain HTTP methods, such as GET and HEAD, do not make any changes to the resource or to the message and are thus considered to be “safe”. Other method are idempotent, which means that the results of multiple identical request are the same as for a single request. All supported methods except POST fall under this category.

The following subset of HTTP methods are supported for the REST BC:

• GET

  The GET method retrieves specific information from the server as identified by the request URI.

• PUT

  The PUT method requests that the message body sent with the request be stored under the location provided in the HTTP message.

• DELETE

  The DELETE method deletes the specified resources.

• POST

  The POST method modifies data on the server from which a request was sent.

• HEAD

  The HEAD method is similar to the GET method except the message body is not returned in the response. The response only includes metainformation, such as a response code or corresponding headers.

REST BC Sample Projects

There are several sample projects for the REST Binding Component to help you get started with the REST BC and further understand the information and instructions provided in this document. To download the samples and read information on how to run them, go to http://wiki.open-esb.java.net/Wiki.jsp?page=RestBCSamples.