org.restlet

## Class Application

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

All Implemented Interfaces:
  Uniform

    public class Application
    extends Restlet

Restlet managing a coherent set of Resources and Services. Applications are guaranteed to receive calls with their base reference set relatively to the VirtualHost that served them. This class is both a descriptor able to create the root Restlet and the actual Restlet that can be attached to one or more VirtualHost instances.
Applications also have many useful services associated. They are all enabled by default and are available as properties that can be eventually overridden:

- "connectorService" to declare necessary client and server connectors.
- "converterService" to convert between regular objects and representations.
- "decoderService" to automatically decode or uncompress request entities.
- "metadataService" to provide access to metadata and their associated extension names.
- "rangeService" to automatically exposes ranges of response entities.
- "statusService" to provide common representations for exception status.
- "taskService" to run tasks asynchronously.
- "tunnelService" to tunnel method names or client preferences via query parameters.

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

### Constructor Summary

Constructors
Constructor and Description
`Application()` Constructor.
`Application(Context context)` Constructor.

### Method Summary

Methods
`Restlet` `createInboundRoot()` Creates a inbound root Restlet that will receive all incoming calls.
`Restlet` `createOutboundRoot()` Creates a outbound root Restlet that will receive all outgoing calls from ClientResource.
`Restlet` `createRoot()` Deprecated. Override the `createInboundRoot()` method instead.
`ConnectorService` `getConnectorService()` Returns the connector service.
`ConverterService` `getConverterService()` Returns the converter service.
`static Application` `getCurrent()` This variable is stored internally as a thread local variable and updated each time a call enters an application.
`DecoderService` `getDecoderService()` Returns the decoder service.
`java.lang.Class<? extends Finder>` `getFinderClass()` Returns the finder class used to instantiate resource classes.
`Restlet` `getInboundRoot()` Returns the inbound root Restlet.
`MetadataService` `getMetadataService()` Returns the metadata service.
`Restlet` `getOutboundRoot()` Returns the outbound root Restlet.
`RangeService` `getRangeService()` Returns the range service.
`Role` `getRole(java.lang.String name)` Returns the role associated to the given name.
`java.util.List<Role>` `getRoles()` Returns the modifiable list of roles.
`Restlet` `getRoot()` Deprecated. Use the `getInboundRoot()` method instead.
`ServiceList` `getServices()` Returns the modifiable list of services.
`StatusService` `getStatusService()` Returns the status service.
`TaskService` `getTaskService()` Returns a task service to run concurrent tasks.
`TunnelService` `getTunnelService()` Returns the tunnel service.
`void` `handle(Request request, Response response)` Handles a call.
`void` `setClientRoot(java.lang.Class<?> clientRootClass)` Sets the client root Resource class.
`void` `setConnectorService(ConnectorService connectorService)` Sets the connector service.
`void` `setContext(Context context)` Sets the context.
`void` `setConverterService(ConverterService converterService)` Sets the converter service.
`static void` `setCurrent(Application application)` Sets the context to associated with the current thread.
`void` `setDecoderService(DecoderService decoderService)` Sets the decoder service.
`void` `setFinderClass(java.lang.Class<? extends Finder> finderClass)` Sets the finder class to instantiate.
`void` `setInboundRoot(java.lang.Class<?> inboundRootClass)` Sets the inbound root Resource class.
`void` `setInboundRoot(Restlet inboundRoot)` Sets the inbound root Restlet.
`void` `setMetadataService(MetadataService metadataService)` Sets the metadata service.
`void` `setOutboundRoot(Restlet outboundRoot)` Sets the outbound root Restlet.
`void` `setRangeService(RangeService rangeService)` Sets the range service.
`void` `setRoles(java.util.List<Role> roles)` Sets the modifiable list of roles.
`void` `setRoot(java.lang.Class<?> inboundRootClass)` Deprecated. Use the `setInboundRoot(Class)` method instead.
`void` `setRoot(Restlet inboundRoot)` Deprecated. Use the `setInboundRoot(Restlet)` method instead.
`void` `setStatusService(StatusService statusService)` Sets the status service.
`void` `setTaskService(TaskService taskService)` Sets the task service.
`void` `setTunnelService(TunnelService tunnelService)` Sets the tunnel service.
`void` `start()` Starts the application, all the enabled associated services then the inbound and outbound roots.
`void` `stop()` Stops the application, the inbound and outbound roots then all the enabled associated services.

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

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

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

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

### Constructor Detail

#### Application

    public Application()

Constructor. Note this constructor is convenient because you don't have to provide a context like for `Application(Context)`. Therefore the context will initially be null. It's only when you attach the application to a virtual host via one of its attach*() methods that a proper context will be set.

#### Application

    public Application(Context context)

Constructor.

Parameters:
  `context` - The context to use based on parent component context. This context should be created using the `Context.createChildContext()` method to ensure a proper isolation with the other applications.

### Method Detail

#### getCurrent

    public static Application getCurrent()

This variable is stored internally as a thread local variable and updated each time a call enters an application. Warning: this method should only be used under duress. You should by default prefer obtaining the current application using methods such as `Handler.getApplication()`

Returns:
  The current context.

#### setCurrent

    public static void setCurrent(Application application)

Sets the context to associated with the current thread.

Parameters:
  `application` - The thread's context.

#### createInboundRoot

    public Restlet createInboundRoot()

Creates a inbound root Restlet that will receive all incoming calls. In general, instances of Router, Filter or Finder classes will be used as initial application Restlet. The default implementation returns null by default. This method is intended to be overridden by subclasses.

Returns:
  The server root Restlet.

#### createOutboundRoot

    public Restlet createOutboundRoot()

Creates a outbound root Restlet that will receive all outgoing calls from ClientResource. In general, instances of Router, Filter or Finder classes will be used as initial application Restlet. The default implementation returns the `Context.getClientDispatcher()` by default. This method is intended to be overridden by subclasses.

Returns:
  The server root Restlet.

#### createRoot

    @Deprecated
    public Restlet createRoot()

Deprecated. Override the `createInboundRoot()` method instead.
Creates a inbound root Restlet that will receive all incoming calls. In general, instances of Router, Filter or Handler classes will be used as initial application Restlet. The default implementation returns null by default. This method is intended to be overridden by subclasses.

Returns:
  The server root Restlet.

#### getConnectorService

    public ConnectorService getConnectorService()

Returns the connector service. The service is enabled by default.

Returns:
  The connector service.

#### getConverterService

    public ConverterService getConverterService()

Returns the converter service. The service is enabled by default.

Returns:
  The converter service.

#### getDecoderService

    public DecoderService getDecoderService()

Returns the decoder service. The service is enabled by default.

Returns:
  The decoder service.

#### getFinderClass

    public java.lang.Class<? extends Finder> getFinderClass()

Returns the finder class used to instantiate resource classes. By default, it returns the `Finder` class. This property is leveraged by `setClientRoot(Class)` and `setInboundRoot(Class)` methods.

Returns:
  the finder class to instantiate.

#### getInboundRoot

    public Restlet getInboundRoot()

Returns the inbound root Restlet.

Returns:
  The inbound root Restlet.

#### getMetadataService

    public MetadataService getMetadataService()

Returns the metadata service. The service is enabled by default.

Returns:
  The metadata service.

#### getOutboundRoot

    public Restlet getOutboundRoot()

Returns the outbound root Restlet.

Returns:
  The outbound root Restlet.

#### getRangeService

    public RangeService getRangeService()

Returns the range service.

Returns:
  The range service.

#### getRole

    public Role getRole(java.lang.String name)

Returns the role associated to the given name.

Parameters:
  `name` - The name of the role to find.
Returns:
  The role matched or null.

#### getRoles

    public java.util.List<Role> getRoles()

Returns the modifiable list of roles.

Returns:
  The modifiable list of roles.

#### getRoot

    @Deprecated
    public Restlet getRoot()

Deprecated. Use the `getInboundRoot()` method instead.
Returns the root inbound Restlet. Invokes the createRoot() method if no inbound root has been set, and stores the Restlet created for future uses.

Returns:
  The root inbound Restlet.

#### getServices

    public ServiceList getServices()

Returns the modifiable list of services.

Returns:
  The modifiable list of services.

#### getStatusService

    public StatusService getStatusService()

Returns the status service. The service is enabled by default.

Returns:
  The status service.

#### getTaskService

    public TaskService getTaskService()

Returns a task service to run concurrent tasks. The service is enabled by default.

Returns:
  A task service.

#### getTunnelService

    public TunnelService getTunnelService()

Returns the tunnel service. The service is enabled by default.

Returns:
  The tunnel 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.

#### setClientRoot

    public void setClientRoot(java.lang.Class<?> clientRootClass)

Sets the client root Resource class.

Parameters:
  `clientRootClass` - The client root Resource class.

#### setConnectorService

    public void setConnectorService(ConnectorService connectorService)

Sets the connector service.

Parameters:
  `connectorService` - The connector service.

#### setContext

    public void setContext(Context context)

Description copied from class: `Restlet`
Sets the context.

Overrides:
  `setContext` in class `Restlet`
Parameters:
  `context` - The context.

#### setConverterService

    public void setConverterService(ConverterService converterService)

Sets the converter service.

Parameters:
  `converterService` - The converter service.

#### setDecoderService

    public void setDecoderService(DecoderService decoderService)

Sets the decoder service.

Parameters:
  `decoderService` - The decoder service.

#### setFinderClass

    public void setFinderClass(java.lang.Class<? extends Finder> finderClass)

Sets the finder class to instantiate. This property is leveraged by `setClientRoot(Class)` and `setInboundRoot(Class)` methods.

Parameters:
  `finderClass` - The finder class to instantiate.

#### setInboundRoot

    public void setInboundRoot(java.lang.Class<?> inboundRootClass)

Sets the inbound root Resource class.

Parameters:
  `inboundRootClass` - The inbound root Resource class.

#### setInboundRoot

    public void setInboundRoot(Restlet inboundRoot)

Sets the inbound root Restlet.

Parameters:
  `inboundRoot` - The inbound root Restlet.

#### setMetadataService

    public void setMetadataService(MetadataService metadataService)

Sets the metadata service.

Parameters:
  `metadataService` - The metadata service.

#### setOutboundRoot

    public void setOutboundRoot(Restlet outboundRoot)

Sets the outbound root Restlet.

Parameters:
  `outboundRoot` - The outbound root Restlet.

#### setRangeService

    public void setRangeService(RangeService rangeService)

Sets the range service.

Parameters:
  `rangeService` - The range service.

#### setRoles

    public void setRoles(java.util.List<Role> roles)

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

Parameters:
  `roles` - A list of roles.

#### setRoot

    @Deprecated
    public void setRoot(java.lang.Class<?> inboundRootClass)

Deprecated. Use the `setInboundRoot(Class)` method instead.
Sets the inbound root Resource class.

Parameters:
  `inboundRootClass` - The inbound root Resource class.

#### setRoot

    @Deprecated
    public void setRoot(Restlet inboundRoot)

Deprecated. Use the `setInboundRoot(Restlet)` method instead.
Sets the inbound root Restlet.

Parameters:
  `inboundRoot` - The inbound root Restlet.

#### setStatusService

    public void setStatusService(StatusService statusService)

Sets the status service.

Parameters:
  `statusService` - The status service.

#### setTaskService

    public void setTaskService(TaskService taskService)

Sets the task service.

Parameters:
  `taskService` - The task service.

#### setTunnelService

    public void setTunnelService(TunnelService tunnelService)

Sets the tunnel service.

Parameters:
  `tunnelService` - The tunnel service.

#### start

    public void start()
               throws java.lang.Exception

Starts the application, all the enabled associated services then the inbound and outbound roots.

Overrides:
  `start` in class `Restlet`
Throws:
  `java.lang.Exception`

#### stop

    public void stop()
              throws java.lang.Exception

Stops the application, the inbound and outbound roots then all the enabled associated services. Finally, it clears the internal cache of annotations.

Overrides:
  `stop` in class `Restlet`
Throws:
  `java.lang.Exception`