org.restlet.service

## Class StatusService

- java.lang.Object
- - org.restlet.service.Service
  - - org.restlet.service.StatusService

    public class StatusService
    extends Service

Service to handle error statuses. If an exception is thrown within your application or Restlet code, it will be intercepted by this service if it is enabled.
When an exception or an error is caught, the `getStatus(Throwable, Request, Response)` method is first invoked to obtain the status that you want to set on the response. If this method isn't overridden or returns null, the `Status.SERVER_ERROR_INTERNAL` constant will be set by default.
Also, when the status of a response returned is an error status (see `Status.isError()`, the `getRepresentation(Status, Request, Response)` method is then invoked to give your service a chance to override the default error page.
If you want to customize the default behavior, you need to create a subclass of StatusService that overrides some or all of the methods mentioned above. Then, just create a instance of your class and set it on your Component or Application via the setStatusService() methods.

Author:
  Jerome Louvel
See Also:
  User Guide

### Constructor Summary

Constructors
Constructor and Description
`StatusService()` Constructor.
`StatusService(boolean enabled)` Constructor.

### Method Summary

Methods
`Filter` `createInboundFilter(Context context)` Create the filter that should be invoked for incoming calls.
`java.lang.String` `getContactEmail()` Returns the email address to contact in case of error.
`Reference` `getHomeRef()` Returns the home URI to propose in case of error.
`Representation` `getRepresentation(Status status, Request request, Response response)` Returns a representation for the given status. In order to customize the default representation, this method can be overridden.
`Status` `getStatus(java.lang.Throwable throwable, Request request, Response response)` Returns a status for a given exception or error.
`Status` `getStatus(java.lang.Throwable throwable, UniformResource resource)` Returns a status for a given exception or error.
`boolean` `isOverwrite()` Deprecated. Use `isOverwriting()` instead.
`boolean` `isOverwriting()` Indicates if an existing entity should be overwritten.
`void` `setContactEmail(java.lang.String contactEmail)` Sets the email address to contact in case of error.
`void` `setHomeRef(Reference homeRef)` Sets the home URI to propose in case of error.
`void` `setOverwrite(boolean overwriting)` Deprecated. Use `setOverwriting(boolean)` instead.
`void` `setOverwriting(boolean overwriting)` Indicates if an existing entity should be overwritten.

### Methods inherited from class org.restlet.service.Service

`createOutboundFilter, getContext, isEnabled, isStarted, isStopped, setContext, setEnabled, start, stop`

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

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

### Constructor Detail

#### StatusService

    public StatusService()

Constructor.

#### StatusService

    public StatusService(boolean enabled)

Constructor.

Parameters:
  `enabled` - True if the service has been enabled.

### Method Detail

#### createInboundFilter

    public Filter createInboundFilter(Context context)

Description copied from class: `Service`
Create the filter that should be invoked for incoming calls.

Overrides:
  `createInboundFilter` in class `Service`
Parameters:
  `context` - The current context.
Returns:
  The new filter or null.

#### getContactEmail

    public java.lang.String getContactEmail()

Returns the email address to contact in case of error. This is typically used when creating the status representations.

Returns:
  The email address to contact in case of error.

#### getHomeRef

    public Reference getHomeRef()

Returns the home URI to propose in case of error.

Returns:
  The home URI to propose in case of error.

#### getRepresentation

    public Representation getRepresentation(Status status,
                                   Request request,
                                   Response response)

Returns a representation for the given status.
In order to customize the default representation, this method can be overridden. It returns null by default.

Parameters:
  `status` - The status to represent.
  `request` - The request handled.
  `response` - The response updated.
Returns:
  The representation of the given status.

#### getStatus

    public Status getStatus(java.lang.Throwable throwable,
                   Request request,
                   Response response)

Returns a status for a given exception or error. By default it unwraps the status of `ResourceException`. For other exceptions or errors, it returns an `Status.SERVER_ERROR_INTERNAL` status.
In order to customize the default behavior, this method can be overridden.

Parameters:
  `throwable` - The exception or error caught.
  `request` - The request handled.
  `response` - The response updated.
Returns:
  The representation of the given status.

#### getStatus

    public Status getStatus(java.lang.Throwable throwable,
                   UniformResource resource)

Returns a status for a given exception or error. By default it returns an `Status.SERVER_ERROR_INTERNAL` status and logs a severe message.
In order to customize the default behavior, this method can be overridden.

Parameters:
  `throwable` - The exception or error caught.
  `resource` - The parent resource.
Returns:
  The representation of the given status.

#### isOverwrite

    @Deprecated
    public boolean isOverwrite()

Deprecated. Use `isOverwriting()` instead.
Indicates if an existing entity should be overwritten. False by default.

Returns:
  True if an existing entity should be overwritten.

#### isOverwriting

    public boolean isOverwriting()

Indicates if an existing entity should be overwritten. False by default.

Returns:
  True if an existing entity should be overwritten.

#### setContactEmail

    public void setContactEmail(java.lang.String contactEmail)

Sets the email address to contact in case of error. This is typically used when creating the status representations.

Parameters:
  `contactEmail` - The email address to contact in case of error.

#### setHomeRef

    public void setHomeRef(Reference homeRef)

Sets the home URI to propose in case of error.

Parameters:
  `homeRef` - The home URI to propose in case of error.

#### setOverwrite

    @Deprecated
    public void setOverwrite(boolean overwriting)

Deprecated. Use `setOverwriting(boolean)` instead.
Indicates if an existing entity should be overwritten.

Parameters:
  `overwriting` - True if an existing entity should be overwritten.

#### setOverwriting

    public void setOverwriting(boolean overwriting)

Indicates if an existing entity should be overwritten.

Parameters:
  `overwriting` - True if an existing entity should be overwritten.