org.restlet

## Class Component

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

All Implemented Interfaces:
  Uniform

    public class Component
    extends Restlet

Restlet managing a set of Connectors, VirtualHosts, Services and Applications. Applications are expected to be directly attached to virtual hosts or to the internal router (see RIAP pseudo-protocol for usage). 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 are dedicated constructors that accept either an URI reference to such XML document or a representation of 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/2.0/Component">
        <client protocol="CLAP" />
        <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>

Components also have useful services associated. They are all enabled by default and are available as properties that can be eventually overridden:

- "logService" to configure access logging.
- "statusService" to provide common representations for exception status.

Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
  Jerome Louvel
See Also:
  Source dissertation

### Constructor Summary

Constructors
Constructor and Description
`Component()` Constructor.
`Component(Reference xmlConfigRef)` Constructor with the reference to the XML configuration file.
`Component(Representation xmlConfigRepresentation)` Constructor with the representation of the XML configuration file.
`Component(java.lang.String xmlConfigurationRef)` Constructor with the URI reference to the XML configuration file.

### Method Summary

Methods
`ClientList` `getClients()` Returns a modifiable list of client connectors.
`VirtualHost` `getDefaultHost()` Returns the default virtual host.
`java.util.List<VirtualHost>` `getHosts()` Returns the modifiable list of virtual hosts.
`Router` `getInternalRouter()` Returns the private internal router where Restlets like Applications can be attached.
`LogService` `getLogService()` Returns the global log service.
`Realm` `getRealm(java.lang.String name)` Finds the realm with the given name.
`java.util.List<Realm>` `getRealms()` Returns the modifiable list of security realms.
`ServerList` `getServers()` Returns the modifiable list of server connectors.
`ServiceList` `getServices()` Returns the modifiable list of services.
`StatusService` `getStatusService()` Returns the status service, enabled by default.
`void` `handle(Request request, Response response)` Handles a call.
`static void` `main(java.lang.String[] args)` Used as bootstrap for configuring and running a component in command line.
`void` `setClients(ClientList clients)` Sets the modifiable list of client connectors.
`void` `setDefaultHost(VirtualHost defaultHost)` Sets the default virtual host.
`void` `setHosts(java.util.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` `setRealms(java.util.List<Realm> realms)` Sets the list of realms.
`void` `setServers(ServerList servers)` Sets the 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` `startRealms()` Starts the realms.
`protected void` `startRouters()` Starts the virtual hosts and the internal router.
`protected void` `startServers()` Starts the server connectors.
`protected void` `startServices()` Starts the associated services.
`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` `stopRealms()` Stops the realms.
`protected void` `stopRouters()` Stops the virtual hosts and the internal router.
`protected void` `stopServers()` Stops the server connectors.
`protected void` `stopServices()` Stops the associated services.
`void` `updateHosts()` Updates the component to take into account changes to the virtual hosts.

### Methods inherited from class org.restlet.Restlet

`finalize, getApplication, getAuthor, getContext, getDescription, getLogger, getName, getOwner, isStarted, isStopped, setAuthor, setContext, setDescription, setName, setOwner`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### Component

    public Component()

Constructor.

#### Component

    public Component(Reference xmlConfigRef)

Constructor with the reference to the XML configuration file.

Parameters:
  `xmlConfigRef` - The URI reference to the XML configuration file.

#### Component

    public Component(Representation xmlConfigRepresentation)

Constructor with the representation of the XML configuration file.

Parameters:
  `xmlConfigRepresentation` - The representation of the XML configuration file.

#### Component

    public Component(java.lang.String xmlConfigurationRef)

Constructor with the URI reference to the XML configuration file.

Parameters:
  `xmlConfigurationRef` - The URI reference to the XML configuration file.

### Method Detail

#### main

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

Used as bootstrap for configuring and running a component in command line. Just provide as first and unique parameter the URI to the XML file. Note that relative paths are accepted.

Parameters:
  `args` - The list of in-line parameters.
Throws:
  `java.lang.Exception`

#### getClients

    public ClientList getClients()

Returns a modifiable list of client connectors.

Returns:
  A modifiable list of client connectors.

#### getDefaultHost

    public VirtualHost getDefaultHost()

Returns the default virtual host.

Returns:
  The default virtual host.

#### getHosts

    public java.util.List<VirtualHost> getHosts()

Returns the modifiable list of virtual hosts. Note that the order of virtual hosts in this list will be used to check the first one that matches.

Returns:
  The modifiable list of virtual hosts.

#### getInternalRouter

    public Router getInternalRouter()

Returns the private internal router where 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 modularization 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 `org.restlet.ext.xml.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 service will be enabled by default and has a logger name composed the "org.restlet." prefix followed by the simple component class name (without packages), followed by the ".LogService" suffix.

Returns:
  The global log service.

#### getRealm

    public Realm getRealm(java.lang.String name)

Finds the realm with the given name.

Parameters:
  `name` - The name.
Returns:
  The realm found or null.

#### getRealms

    public java.util.List<Realm> getRealms()

Returns the modifiable list of security realms.

Returns:
  The modifiable list of security realms.

#### getServers

    public ServerList getServers()

Returns the modifiable list of server connectors.

Returns:
  The modifiable list of server connectors.

#### getServices

    public ServiceList getServices()

Returns the modifiable list of services.

Returns:
  The modifiable list of services.

#### getStatusService

    public StatusService getStatusService()

Returns the status service, enabled by default.

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 initialize the Restlet by setting the current context using the `Context.setCurrent(Context)` method and by attempting to start it, unless it was already started. If an exception is thrown during the start action, then the response status is set to `Status.SERVER_ERROR_INTERNAL`.

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

Specified by:
  `handle` in interface `Uniform`
Overrides:
  `handle` in class `Restlet`
Parameters:
  `request` - The request to handle.
  `response` - The response to update.

#### setClients

    public void setClients(ClientList clients)

Sets the modifiable list of client connectors. This method clears the current list and adds all entries in the parameter list.

Parameters:
  `clients` - A 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(java.util.List<VirtualHost> hosts)

Sets the modifiable list of virtual hosts. Note that the order of virtual hosts in this list will be used to check the first one that matches. This method clears the current list and adds all entries in the parameter list.

Parameters:
  `hosts` - A 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.

#### setRealms

    public void setRealms(java.util.List<Realm> realms)

Sets the list of realms. This method clears the current list and adds all entries in the parameter list.

Parameters:
  `realms` - A list of realms.

#### setServers

    public void setServers(ServerList servers)

Sets the modifiable list of server connectors. This method clears the current list and adds all entries in the parameter list.

Parameters:
  `servers` - A list of server connectors.

#### setStatusService

    public void setStatusService(StatusService statusService)

Sets the status service.

Parameters:
  `statusService` - The status service.

#### start

    public void start()
               throws java.lang.Exception

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

Overrides:
  `start` in class `Restlet`
Throws:
  `java.lang.Exception`
See Also:
  `startClients()`, `startServers()`, `startRouters()`, `startServices()`, `startRealms()`, `startHelper()`

#### startClients

    protected void startClients()
                         throws java.lang.Exception

Starts the client connectors.

Throws:
  `java.lang.Exception`

#### startHelper

    protected void startHelper()
                        throws java.lang.Exception

Starts the internal helper allowing incoming requests to be served.

Throws:
  `java.lang.Exception`

#### startRealms

    protected void startRealms()
                        throws java.lang.Exception

Starts the realms.

Throws:
  `java.lang.Exception`

#### startRouters

    protected void startRouters()
                         throws java.lang.Exception

Starts the virtual hosts and the internal router.

Throws:
  `java.lang.Exception`

#### startServers

    protected void startServers()
                         throws java.lang.Exception

Starts the server connectors.

Throws:
  `java.lang.Exception`

#### startServices

    protected void startServices()
                          throws java.lang.Exception

Starts the associated services.

Throws:
  `java.lang.Exception`

#### stop

    public void stop()
              throws java.lang.Exception

Stops the component. First it stops the component's internal helper, the realms, the services, the routers 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:
  `java.lang.Exception`
See Also:
  `stopHelper()`, `stopRealms()`, `stopServices()`, `stopRouters()`, `stopServers()`, `stopClients()`

#### stopClients

    protected void stopClients()
                        throws java.lang.Exception

Stops the client connectors.

Throws:
  `java.lang.Exception`

#### stopHelper

    protected void stopHelper()
                       throws java.lang.Exception

Stops the internal helper allowing incoming requests to be served.

Throws:
  `java.lang.Exception`

#### stopRealms

    protected void stopRealms()
                       throws java.lang.Exception

Stops the realms.

Throws:
  `java.lang.Exception`

#### stopRouters

    protected void stopRouters()
                        throws java.lang.Exception

Stops the virtual hosts and the internal router.

Throws:
  `java.lang.Exception`

#### stopServers

    protected void stopServers()
                        throws java.lang.Exception

Stops the server connectors.

Throws:
  `java.lang.Exception`

#### stopServices

    protected void stopServices()
                         throws java.lang.Exception

Stops the associated services.

Throws:
  `java.lang.Exception`

#### updateHosts

    public void updateHosts()
                     throws java.lang.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:
  `java.lang.Exception`