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.

In case the response's entity has already been set, the status service does not generate an error representation. You can turn off this default behavior by calling the setOverwriting(boolean) method.

Author:

Jerome Louvel

See Also:

User Guide

Constructor Summary

Constructors

Constructor and Description
StatusService() Constructor.
StatusService(boolean enabled) Constructor.
StatusService(boolean enabled, ConverterService converterService, MetadataService metadataService, ConnegService connegService) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
Filter	createInboundFilter(Context context) Create the filter that should be invoked for incoming calls.
ConnegService	getConnegService() Returns the service used to select the preferred variant.
String	getContactEmail() Returns the email address to contact in case of error.
ConverterService	getConverterService() Returns the service used to convert between status/throwable and representation.
Reference	getHomeRef() Returns the home URI to propose in case of error.
MetadataService	getMetadataService() Returns the service used to select the preferred variant.
Representation	getRepresentation(Status status, Request request, Response response) Deprecated. Use toRepresentation(Status, Request, Response) instead.
Status	getStatus(Throwable throwable, Request request, Response response) Deprecated. Use toStatus(Throwable, Request, Response) instead.
Status	getStatus(Throwable throwable, Resource resource) Deprecated. Use toStatus(Throwable, Resource) instead.
boolean	isOverwriting() Indicates if an existing entity should be overwritten.
void	setConnegService(ConnegService connegService) Sets the service used to select the preferred variant.
void	setContactEmail(String contactEmail) Sets the email address to contact in case of error.
void	setConverterService(ConverterService converterService) Sets the service used to convert between status/throwable and representation.
void	setHomeRef(Reference homeRef) Sets the home URI to propose in case of error.
void	setMetadataService(MetadataService metadataService) Sets the service used to select the preferred variant.
void	setOverwriting(boolean overwriting) Indicates if an existing entity should be overwritten.
Representation	toRepresentation(Status status, Request request, Response response) Returns a representation for the given status.
Representation	toRepresentation(Status status, Resource resource) Returns a representation for the given status. In order to customize the default representation, this method can be overridden.
Status	toStatus(Throwable throwable, Request request, Response response) Returns a status for a given exception or error.
Status	toStatus(Throwable throwable, Resource resource) Returns a status for a given exception or error.

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. By default, it creates the necessary services.

StatusService

public StatusService(boolean enabled)

Constructor. By default, it creates the necessary services.

Parameters:

enabled - True if the service has been enabled.

StatusService

public StatusService(boolean enabled,
             ConverterService converterService,
             MetadataService metadataService,
             ConnegService connegService)

Constructor.

Parameters:

enabled - True if the service has been enabled.

converterService - The service used to convert between status/throwable and representation.

metadataService - The service used to select the preferred variant.

connegService - The service used to select the preferred variant.

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.

getConnegService

public ConnegService getConnegService()

Returns the service used to select the preferred variant.

Returns:

The service used to select the preferred variant.

getContactEmail

public 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.

getConverterService

public ConverterService getConverterService()

Returns the service used to convert between status/throwable and representation.

Returns:

The service used to convert between status/throwable and representation.

getHomeRef

public Reference getHomeRef()

Returns the home URI to propose in case of error.

Returns:

The home URI to propose in case of error.

getMetadataService

public MetadataService getMetadataService()

Returns the service used to select the preferred variant.

Returns:

The service used to select the preferred variant.

getRepresentation

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

Deprecated. Use toRepresentation(Status, Request, Response) instead.

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

@Deprecated
public Status getStatus(Throwable throwable,
                          Request request,
                          Response response)

Deprecated. Use toStatus(Throwable, Request, Response) instead.

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

@Deprecated
public Status getStatus(Throwable throwable,
                          Resource resource)

Deprecated. Use toStatus(Throwable, Resource) instead.

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.

isOverwriting

public boolean isOverwriting()

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

Returns:

True if an existing entity should be overwritten.

setConnegService

public void setConnegService(ConnegService connegService)

Sets the service used to select the preferred variant.

Parameters:

connegService - The service used to select the preferred variant.

setContactEmail

public void setContactEmail(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.

setConverterService

public void setConverterService(ConverterService converterService)

Sets the service used to convert between status/throwable and representation.

Parameters:

converterService - The service used to convert between status/throwable and representation.

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.

setMetadataService

public void setMetadataService(MetadataService metadataService)

Sets the service used to select the preferred variant.

Parameters:

metadataService - The service used to select the preferred variant.

setOverwriting

public void setOverwriting(boolean overwriting)

Indicates if an existing entity should be overwritten.

Parameters:

overwriting - True if an existing entity should be overwritten.

toRepresentation

public Representation toRepresentation(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 a Status representation by default or a Throwable representation if the throwable is annotated with Status.

Parameters:

status - The status to represent.

request - The request handled.

response - The response updated.

Returns:

The representation of the given status.

toRepresentation

public Representation toRepresentation(Status status,
                              Resource resource)

Returns a representation for the given status.
In order to customize the default representation, this method can be overridden. By default it invokes toRepresentation(Status, Request, Response)

Parameters:

status - The status to represent.

resource - The parent resource.

Returns:

The representation of the given status.

toStatus

public Status toStatus(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.

toStatus

public Status toStatus(Throwable throwable,
              Resource 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.