org.restlet
Class Component

java.lang.Object
  org.restlet.Uniform
      org.restlet.Restlet
          org.restlet.Component

public class Component
extends Restlet

Restlet managing a set of Connectors, VirtualHosts and Applications. Applications are expected to be directly attached to VirtualHosts. Components also expose several services: access logging and status setting.

From an architectural point of view, here is the REST definition: "A component is an abstract unit of software instructions and internal state that provides a transformation of data via its interface." Roy T. Fielding

The configuration of a Component can be done programmatically or by using a XML document. There is a dedicated constructor that accepts an URI reference to such XML document, allowing easy configuration of the list of supported client and server connectors as well as services. In addition, you can add and configure virtual hosts (including the default one). Finally, you can attach applications either using their fully qualified class name or by pointing to a descriptor document (at this time only WADL description are supported, see the WADL Restlet extension for details).

The XML Schema of the configuration files is available both online and inside the API JAR under the "org.restlet.Component.xsd" name.

Here is a sample of XML configuration:

 <?xml version="1.0"?>
 <component xmlns="http://www.restlet.org/schemas/1.1/Component"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.restlet.org/schemas/1.1/Component">
    <client protocol="FILE" />
    <client protocols="HTTP HTTPS" />
    <server protocols="HTTP HTTPS" />
 
    <defaultHost>
       <attach uriPattern="/abcd/{xyz}" 
                  targetClass="org.restlet.test.MyApplication" />
       <attach uriPattern="/efgh/{xyz}"
                  targetDescriptor="clap://class/org.restlet.test.MyApplication.wadl" />
    </defaultHost>
 </component>
 

Author:

Jerome Louvel (contact@noelios.com)

See Also:

Source dissertation

Constructor Summary

Component()
Constructor.

Component(Reference xmlConfigReference)
Parse a configuration file and update the component's configuration.

Method Summary

ClientList	getClients() Returns a modifiable list of client connectors.
VirtualHost	getDefaultHost() Returns the default virtual host.
List<VirtualHost>	getHosts() Returns the modifiable list of virtual hosts.
Router	getInternalRouter() Returns the private internal router were Restlets like Applications can be attached.
LogService	getLogService() Returns the global log service.
ServerList	getServers() Returns the modifiable list of server connectors.
StatusService	getStatusService() Returns the status service, enabled by default.
void	handle(Request request, Response response) Handles a call.
static void	main(String[] args) Used as bootstrap for configuring and running a component in command line.
void	setClients(ClientList clients) Sets a modifiable list of client connectors.
void	setDefaultHost(VirtualHost defaultHost) Sets the default virtual host.
void	setHosts(List<VirtualHost> hosts) Sets the modifiable list of virtual hosts.
void	setInternalRouter(Router internalRouter) Sets the private internal router were Restlets like Applications can be attached.
void	setLogService(LogService logService) Sets the global log service.
void	setServers(ServerList servers) Sets a modifiable list of server connectors.
void	setStatusService(StatusService statusService) Sets the status service.
void	start() Starts the component.
protected void	startClients() Starts the client connectors.
protected void	startHelper() Starts the internal helper allowing incoming requests to be served.
protected void	startServers() Starts the server connectors.
void	stop() Stops the component.
protected void	stopClients() Stops the client connectors.
protected void	stopHelper() Stops the internal helper allowing incoming requests to be served.
protected void	stopServers() Stops the server connectors.
void	updateHosts() Updates the component to take into account changes to the virtual hosts.

Methods inherited from class org.restlet.Restlet

getApplication, getContext, getLogger, init, isStarted, isStopped, setContext

Methods inherited from class org.restlet.Uniform

delete, delete, get, get, handle, head, head, options, options, post, post, put, put

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Component

public Component()

Constructor.

Component

public Component(Reference xmlConfigReference)

Parse a configuration file and update the component's configuration.

Parameters:

xmlConfigReference - The reference to the XML config file.

Method Detail

getClients

public ClientList getClients()

Returns a modifiable list of client connectors. Creates a new instance if no one has been set.

Returns:

A modifiable list of client connectors.

getDefaultHost

public VirtualHost getDefaultHost()

Returns the default virtual host.

Returns:

The default virtual host.

getHosts

public List<VirtualHost> getHosts()

Returns the modifiable list of virtual hosts. Creates a new instance if no one has been set.

Returns:

The modifiable list of virtual hosts.

getInternalRouter

public Router getInternalRouter()

Returns the private internal router were Restlets like Applications can be attached. Those Restlets can be addressed via the Protocol.RIAP (Restlet Internal Access Protocol) client connector. This is used to manage private, internal and optimized access to local applications.

The first use case is the modularisation of a large application into modules or layers. This can also be achieved using the Context.getServerDispatcher() method, but the internal router is easily addressable via an URI scheme and can be fully private to the current Component.

The second use case is the composition/mash-up of several representations via the Transformer class for example. For this you can leverage the XPath's document() function or the XSLT's include and import elements with RIAP URIs.

Returns:

The private internal router.

getLogService

public LogService getLogService()

Returns the global log service. On the first call, if no log service was defined via the setLogService(LogService) method, then a default logger service is created. This default service is enabled by default and has a logger name composed of the canonical name of the current component's class or subclass, appended with the instance hash code between parenthesis (eg. "com.mycompany.MyComponent(1439)").

Returns:

The global log service.

getServers

public ServerList getServers()

Returns the modifiable list of server connectors. Creates a new instance if no one has been set.

Returns:

The modifiable list of server connectors.

getStatusService

public StatusService getStatusService()

Returns the status service, enabled by default. Creates a new instance if no one has been set.

Returns:

The status service.

handle

public void handle(Request request,
                   Response response)

Description copied from class: Restlet

Handles a call. The default behavior is to call the (now deprecated) Restlet.init(Request, Response) method. In next version, Restlet.init(Request, Response) will be removed and its logic directly added to this method instead.

Subclasses overriding this method should make sure that they call super.handle(request, response) before adding their own logic.

Overrides:

handle in class Restlet

Parameters:

request - The request to handle.

response - The response to update.

setClients

public void setClients(ClientList clients)

Sets a modifiable list of client connectors. Method synchronized to make compound action (clear, addAll) atomic, not for visibility.

Parameters:

clients - A modifiable list of client connectors.

setDefaultHost

public void setDefaultHost(VirtualHost defaultHost)

Sets the default virtual host.

Parameters:

defaultHost - The default virtual host.

setHosts

public void setHosts(List<VirtualHost> hosts)

Sets the modifiable list of virtual hosts. Method synchronized to make compound action (clear, addAll) atomic, not for visibility.

Parameters:

hosts - The modifiable list of virtual hosts.

setInternalRouter

public void setInternalRouter(Router internalRouter)

Sets the private internal router were Restlets like Applications can be attached.

Parameters:

internalRouter - The private internal router.

See Also:

getInternalRouter()

setLogService

public void setLogService(LogService logService)

Sets the global log service.

Parameters:

logService - The global log service.

setServers

public void setServers(ServerList servers)

Sets a modifiable list of server connectors. Method synchronized to make compound action (clear, addAll) atomic, not for visibility.

Parameters:

servers - A modifiable list of server connectors.

setStatusService

public void setStatusService(StatusService statusService)

Sets the status service.

Parameters:

statusService - The status service.

start

public void start()
           throws Exception

Starts the component. First it starts all the connectors (clients then servers) and then starts the component's internal helper. Finally it calls the start method of the super class.

Overrides:

start in class Restlet

Throws:

Exception

See Also:

startClients(), startServers(), startHelper()

startClients

protected void startClients()
                     throws Exception

Starts the client connectors.

Throws:

Exception

startHelper

protected void startHelper()
                    throws Exception

Starts the internal helper allowing incoming requests to be served.

Throws:

Exception

startServers

protected void startServers()
                     throws Exception

Starts the server connectors.

Throws:

Exception

stop

public void stop()
          throws Exception

Stops the component. First it stops the component's internal helper and then stops all the connectors (servers then clients). Finally it calls the stop method of the super class.

Overrides:

stop in class Restlet

Throws:

Exception

See Also:

stopHelper(), stopServers(), stopClients()

stopClients

protected void stopClients()
                    throws Exception

Stops the client connectors.

Throws:

Exception

stopHelper

protected void stopHelper()
                   throws Exception

Stops the internal helper allowing incoming requests to be served.

Throws:

Exception

stopServers

protected void stopServers()
                    throws Exception

Stops the server connectors.

Throws:

Exception

updateHosts

public void updateHosts()
                 throws Exception

Updates the component to take into account changes to the virtual hosts. This method doesn't stop the connectors or the applications or Restlets attached to the virtual hosts. It just updates the internal routes between the virtual hosts and the attached Restlets or applications.

Throws:

Exception

main

public static void main(String[] args)
                 throws Exception

Used as bootstrap for configuring and running a component in command line. Just provide as first and unique parameter the path to the XML file.

Parameters:

args - The list of in-line parameters.

Throws:

Exception