Connectors

http://restlet.org/learn/guide/2.2/core/base/connectors/

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.

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.

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 Restlet 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. Here are the commons parameters dedicated to internal connectors.

commons parameters:

Parameter name	Value type	Default value	Description
controllerDaemon	boolean	true (client), false (server)	Indicates if the controller thread should be a daemon (not blocking JVM exit).
controllerSleepTimeMs	int	60 000	Time for the controller thread to sleep between each control. A value strictly superior to 0 is required.
minThreads	int	1	Minimum number of worker threads waiting to service calls, even if they are idle. Technically speaking, this is a core number of threads that are pre-started.
lowThreads	int	8	Number of worker threads determining when the connector is considered overloaded. This triggers some protection actions such as not accepting new connections.
maxThreads	int	10	Maximum number of worker threads that can service calls. If this number is reached then additional calls are queued if the "maxQueued" value hasn't been reached.
maxQueued	int	0	Maximum number of calls that can be queued if there aren't any worker thread available to service them. If the value is '0', then no queue is used and calls are rejected if no worker thread is immediately available. If the value is '-1', then an unbounded queue is used and calls are never rejected. Note: make sure that this value is consistent with getMinThreads() and the behavior of the ThreadPoolExecutor configured internally.
maxIoIdleTimeMs	int	60 000	Maximum time for an idle IO connection or request to wait for an operation before being closed. For an unlimited wait, use '0' as value.
maxThreadIdleTimeMs	int	300 000	Time for an idle thread to wait for an operation before being collected.
tracing	boolean	false	Indicates if all messages should be printed on the standard console.
workerThreads	boolean	true	Indicates if the processing of calls should be done via threads provided by a worker service (i.e. a pool of worker threads). Note that if set to false, calls will be processed a single IO selector thread, which should never block, otherwise the other connections would hang.
inboundBufferSize	int	16 * 1024	Size of the content buffer for receiving messages.
outboundBufferSize	int	32 * 1024	Size of the content buffer for sending messages.
directBuffers	boolean	false	Indicates if direct NIO buffers should be allocated instead of regular buffers. See NIO's ByteBuffer Javadocs. Note that tracing must be disabled to use direct buffers.
throttleTimeMs	int	0	Time to wait between socket write operations in milliseconds. Can prevent TCP buffer overflows.
transport	String	TCP	Indicates the transport protocol such as TCP or UDP.

Server connectors

Here are the commons parameters dedicated to non-internal HTTP server connectors.

Parameter name	Value type	Default value	Description
useForwardedForHeader	boolean	false	Lookup the "X-Forwarded-For" header supported by popular proxies and caches and uses it to populate the Request.getClientAddresses() method result. This information is only safe for intermediary components within your local network. Other addresses could easily be changed by setting a fake header and should not be trusted for serious security checks.
adapter	String	org.restlet.engine.adapter.ServerAdapter	Class name of the adapter of low-level HTTP calls into high level requests and responses.

Here are the  commons parameters  dedicated to internal HTTP server connectors.

Parameter name	Value type	Default value	Description
useForwardedForHeader	boolean	false	Lookup the "X-Forwarded-For" header supported by popular proxies and caches and uses it to populate the Request.getClientAddresses() method result. This information is only safe for intermediary components within your local network. Other addresses could easily be changed by setting a fake header and should not be trusted for serious security checks.
reuseAddress	boolean	true	Enable/disable the SO_REUSEADDR socket option. See java.io.ServerSocket#reuseAddress property for additional details.

Here is a sample code showing how to set such a parameter on a component's server connector.

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

Client connectors

Here are the commons parameters dedicated to non-internal HTTP client connectors.

Parameter name	Value type	Default value	Description
adapter	String	org.restlet.engine.adapter.ClientAdapter	Class name of the adapter of low-level HTTP calls into high level requests and responses.

Here are the commons parameters dedicated to internal HTTP client connectors.

Parameter name	Value type	Default value	Description
proxyHost	String	System property "http.proxyHost"	The host name of the HTTP proxy.
proxyPort	int	System property "http.proxyPort"	The port of the HTTP proxy.
socketConnectTimeoutMs	int	0	The socket connection timeout or 0 for unlimited wait.

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

Client client = new Client(new Context(), Protocol.HTTP);
client.getContext().getParameters().add("useForwardedForHeader","false");

Here is a sample code showing how to set such a parameter on a component's client connector.

// Create the HTTP server and listen on port 8182
Component c = new Component();
Client client = c.getClients().add(Protocol.HTTP);
client.getContext().getParameters().add("useForwardedForHeader", "false");

If you want to configure the client connector used by a ClientResource, there are several cases. When your ClientResource instances are created in the context of an application hosted by a Component, the client connector of the component is used for all requests. Thus, just configure the component's client connector as shown just above. If not, just set it:

// Instantiate the client connector, and configure it.
Client client = new Client(new Context(), Protocol.HTTP);
client.getContext().getParameters().add("useForwardedForHeader","false");

// Instantiate the ClientResource, and set it's client connector.
ClientResource cr = new ClientResource("http://www.example.com/");
cr.setNext(client);

List of available connectors

Server connectors

Extension	Version	Protocols	Asynchronous	Comment
Internal	2.2	HTTP, HTTPS, RIAP	Yes	Recommended for development
Jetty	7.0	HTTP, HTTPS, AJP	No	Recommended for robust and scalable deployments
Simple	4.1	HTTP, HTTPS	No	Recommended for lightweight deployments
Servlet	2.5	HTTP, HTTPS, AJP	No	Recommended for deployments inside Java EE servers

Client connectors

Extension	Version	Protocols	Asynchronous	Proxy	Comment
Internal	2.2	HTTP, HTTPS, CLAP, FILE, FTP, RIAP	Yes	No	Stable but HTTP connectors are recommended for development only
Apache HTTP Client	4.0	HTTP, HTTPS	No	Yes	Recommended for robust and scalable deployments
JavaMail	1.4	SMTP, SMTPS, POP, POPS	No	No	Stable
JDBC	3.0	JDBC	No	No	Stable
Lucene Solr	2.9	SOLR	No	No	Stable
NIO	2.2	HTTP, HTTPS	No	Yes	Fully asynchronous, preview mode