Restlet 1.0 - Connectors

Introduction

A connector in the REST architecture style is a software element that manages network communication for a component, typically by implementing a network protocol (e.g. HTTP). A client connector initiates communication with a server (of any kind) by creating a request. A server connector listens for connections (from clients of any kind), transmits the request to the component that performs the request processing, creates the response and sends it to the client.

All connectors are provided as extensions of the Noelios Restlet Engine, the reference implementation of the Restlet API.

This document will describe how to add a connector to your application, how to configure it and will give you the list of available server and client connectors.

Add a connector to your application

All connectors and their dependencies are shipped with the Restlet distribution by the way of jar files. Adding a connector to your application is as simple as adding the archives of the chosen connector and its dependencies to the classpath.
You can also have a look to the FAQ #4 and FAQ #5 which completes this subject.

Configuration

Each connector looks for its configuration from its context. The latter provides a list of modifiable parameters, which is the right place to set up the connector's configuration. Some parameters are defined by the NRE engine and thus are shared by all clients (in the ClientHelper hierarchy) and server connectors (in the ServerHelper hierarchy), and most of them by the connector's ClientHelper or ServerHelper subclasses.

The list of all parameters are available in the javadocs. Pleaser refer to the rest of this document for references to these documentation.

List of available connectors

Server Connectors

Configuration

Here are the commons parameters dedicated to HTTP server connectors.

Here is a sample code showing how to set such a parameter.

// Creating a minimal Restlet returning "Hello World"
Restlet restlet = new Restlet() {
    @Override
    public void handle(Request request, Response response) {
        response.setEntity("Hello World!", MediaType.TEXT_PLAIN);
    }
};

// Create the HTTP server and listen on port 8182
Server server = new Server(Protocol.HTTP, 8182, restlet);
server.getContext().getParameters().add("useForwardedForHeader", "true");
server.start();

AsyncWeb

This connector is based on the open source project AsyncWeb. This is an Java HTTP engine, based on the MINA framework. Thus, it employs non blocking IO and has been designed to allow highly scalability and support of very high throughput.

This connector supports the following protocol: HTTP.

The list of supported specific parameters is available in the javadocs:

Here is the list of dependencies of this connector:

Jetty

This connector is based on the Jetty open-source web server. Jetty is popular and has a nice separation between its HTTP protocol implementation and its support for the Servlet API which led it to be the first HTTP server connector developed for the Restlet.

This connector supports the following protocols: HTTP, HTTPS, AJP.

The list of supported specific parameters is available in the javadocs:

Here is the list of dependencies of this connector:

Simple

This connector is based on Simple 3.1 which is an open source embeddable Java based HTTP engine capable of handling high loads.

This connector supports the following protocols: HTTP, HTTPS.

The list of supported specific parameters is available in the javadocs:

Here is the list of dependencies of this connector:

Client Connectors

Configuration

Here are the commons parameters dedicated to HTTP client connectors.

Here is a sample code showing how to set such a parameter.

Client client = new Client(Protocol.HTTP);
client.getContext().getParameters().add("converter",
                       "com.noelios.restlet.http.HttpClientConverter");

Apache HTTP Client

This connector is based on Apache Commons HTTP client. It provides an HTTP and HTTPS client connector with advanced multi-threading and connection reuse support.

As pointed out by the Apache HTTPClient tutorial it is crucial to read entirely each response. It allows to release the underlying connection. Not doing so may cause future requests to block.
See Apache HTTPClient 3.x tutorial.

This connector supports the following protocols: HTTP, HTTPS.

The list of supported specific parameters is available in the javadocs:

Here is the list of dependencies of this connector:

Net

This connector is fully based on the JDK and more precisely on java.net.HttpURLConnection class.

This connector supports the following protocols: HTTP, HTTPS.

The list of supported specific parameters is available in the javadocs:

JavaMail

This connector is based on JavaMail that provides a platform-independent and protocol-independent framework to build mail and messaging applications.

This connector supports the following protocols: SMTP, SMTPS.

The mail and its properties (sender, recipient, subject, content, etc) have to be specified as an XML representation. Please refer to the JavaMail client javadocs for more details.

Here is the list of dependencies of this connector:

JDBC

This connector is a client to a JDBC database. It is based on the JDBC Api developed by Sun Microsystems and shipped with the JDK. Database connections are optionally pooled using Apache Commons DBCP. In this case, a different connection pool is created for each unique combination of JDBC URI and connection properties.

This connector supports the following protocol: JDBC.

The SQL request and other kinds of parameters (such as pooling) are passed to the client connector via an XML representation. Please refer to the JDBC client javadocs for more details.
The Response provides the result of the SQL request as a RowSetRepresentation which is a kind of XML representation of the ResultSet instance wrapped either in a JdbcResult or in a WebRowSet instance. See the RowSetRepresentation for more details.

Here is the list of dependencies of this connector:

NRE Local client

This internal connector is shipped with the Noelios Restlet Engine distribution and gives access to non-remote resources located on a local file system or managed by a classloader.

This connector supports the following protocols: FILE, CLAP.

FILE is a standard scheme to access to representations stored in the file system (e.g.: "file:///d:/temp/fichier.txt", "file:///tmp/fichier.txt"). CLAP (ClassLoader Access Protocol) is a custom scheme to access to representations via classloaders (e.g.: clap://thread/org/restlet/Restlet.class). This protocol accepts three kinds of authority :

The "local" Reference instances can be easily created via the LocalReference class.
The list of supported parameters is available in the javadocs: