uws.service.error

Class DefaultUWSErrorWriter

java.lang.Object

uws.service.error.DefaultUWSErrorWriter

All Implemented Interfaces:

ServiceErrorWriter

public class DefaultUWSErrorWriter
extends java.lang.Object
implements ServiceErrorWriter

Default implementation of a ServiceErrorWriter interface for a UWS service.

All errors are written using the function formatError(String, ErrorType, int, String, String, JobOwner, HttpServletResponse, String) in order to format the error in the most appropriate format. 2 formats are managed by default by this implementation: HTML (default) and JSON. This format is chosen thanks to the "Accept" header of the HTTP request. If no request is provided or if there is no known format, the HTML format is chosen by default.

UWSExceptions may precise the HTTP error code to apply, which will be used to set the HTTP status of the response. If it is a different kind of exception, the HTTP status 500 (INTERNAL SERVER ERROR) will be used.

Besides, all exceptions except UWSException and TAPException will be logged as FATAL in the TAP context (with no event and no object). Thus the full stack trace is available to the administrator so that the error can be understood as easily and quickly as possible. The stack trace is no longer displayed to the user.

Version:

4.2 (09/2017)

Author:

Grégory Mantelet (CDS;ARI)

Field Summary

Fields

Modifier and Type	Field and Description
protected UWSLog	logger Logger to use when grave error must be logged or if a JSON error occurs.
protected java.lang.String[]	managedFormats List of all managed output formats.

Constructor Summary

Constructors

Constructor and Description
DefaultUWSErrorWriter(UWSLog logger) Build an error writer which will log any error in response of an HTTP request.

Method Summary

Modifier and Type	Method and Description
protected java.lang.String	chooseFormat(java.lang.String acceptHeader) Parses the header "Accept", splits it in a list of MIME type and compare each one to each managed formats (managedFormats).
protected void	formatError(java.lang.String message, ErrorType type, int httpErrorCode, java.lang.String reqID, java.lang.String action, JobOwner user, javax.servlet.http.HttpServletResponse response, java.lang.String acceptHeader) Formats and writes the given error in the HTTP servlet response.
protected void	formatHTMLError(java.lang.String message, ErrorType type, int httpErrorCode, java.lang.String reqID, java.lang.String action, JobOwner user, javax.servlet.http.HttpServletResponse response) Formats and writes the given error in the HTTP servlet response.
protected void	formatJSONError(java.lang.String message, ErrorType type, int httpErrorCode, java.lang.String reqID, java.lang.String action, JobOwner user, javax.servlet.http.HttpServletResponse response) Formats and writes the given error in the HTTP servlet response.
java.lang.String	getErrorDetailsMIMEType() Get the MIME type of the error details written by ServiceErrorWriter.writeError(Throwable, ErrorSummary, UWSJob, OutputStream) in the error summary.
boolean	writeError(java.lang.String message, ErrorType type, int httpErrorCode, javax.servlet.http.HttpServletResponse response, javax.servlet.http.HttpServletRequest request, java.lang.String reqID, JobOwner user, java.lang.String action) Write the described error in the given response.
void	writeError(java.lang.Throwable t, ErrorSummary error, UWSJob job, java.io.OutputStream output) Write the given error in the given output stream.
boolean	writeError(java.lang.Throwable t, javax.servlet.http.HttpServletResponse response, javax.servlet.http.HttpServletRequest request, java.lang.String reqID, JobOwner user, java.lang.String action) Write the given exception in the given response.

Methods inherited from class java.lang.Object

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

Field Detail

managedFormats

protected final java.lang.String[] managedFormats

List of all managed output formats.

logger

protected final UWSLog logger

Logger to use when grave error must be logged or if a JSON error occurs.

Constructor Detail

DefaultUWSErrorWriter

public DefaultUWSErrorWriter(UWSLog logger)

Build an error writer which will log any error in response of an HTTP request.

Parameters:

logger - Object to use to log errors.

Method Detail

writeError

public boolean writeError(java.lang.Throwable t,
                          javax.servlet.http.HttpServletResponse response,
                          javax.servlet.http.HttpServletRequest request,
                          java.lang.String reqID,
                          JobOwner user,
                          java.lang.String action)

Description copied from interface: ServiceErrorWriter

Write the given exception in the given response.

Note: If this function is called without at least an exception and an HTTP response, nothing should be done. No error may be thrown.

IMPORTANT: If any IOException occurs while writing the error in the given HttpServletResponse output stream, this function should stop and return false. In such case, the error which was supposed to be written may be logged.

Specified by:

writeError in interface ServiceErrorWriter

Parameters:

t - Exception to write/format.

response - Response in which the given exception must be written.

request - Request at the origin of the error (MAY BE NULL).

reqID - ID of the request (which let the user and the administrator identify the failed request). (MAY BE NULL if the request is not provided)

user - User which sends the given request (which generates the error) (MAY BE NULL).

action - Type/Name of the action which generates the error (MAY BE NULL).

Returns:

true if the given error message has been successfully written in the given HttpServletResponse, false otherwise.

writeError

public boolean writeError(java.lang.String message,
                          ErrorType type,
                          int httpErrorCode,
                          javax.servlet.http.HttpServletResponse response,
                          javax.servlet.http.HttpServletRequest request,
                          java.lang.String reqID,
                          JobOwner user,
                          java.lang.String action)

Description copied from interface: ServiceErrorWriter

Write the described error in the given response.

Note: If this function is called without at least a message and an HTTP response, nothing should be done. No error may be thrown.

IMPORTANT: If any IOException occurs while writing the error in the given HttpServletResponse output stream, this function should stop and return false. In such case, the error which was supposed to be written may be logged.

Specified by:

writeError in interface ServiceErrorWriter

Parameters:

message - Message to display.

type - Type of the error: FATAL or TRANSIENT.

httpErrorCode - HTTP error code (i.e. 404, 500).

response - Response in which the described error must be written.

request - Request which causes this error.

reqID - ID of the request (which let the user and the administrator identify the failed request).

user - User which sends the HTTP request.

action - Action corresponding to the given request.

Returns:

true if the given error message has been successfully written in the given HttpServletResponse, false otherwise.

writeError

public void writeError(java.lang.Throwable t,
                       ErrorSummary error,
                       UWSJob job,
                       java.io.OutputStream output)
                throws java.io.IOException

Description copied from interface: ServiceErrorWriter

Write the given error in the given output stream.

This function is used only for the error summary of a job (that's to say to report in the ../error/details parameter any error which occurs while executing a job).

Important note: The error details written in the given output MUST always have the same MIME type. This latter MUST be returned by ServiceErrorWriter.getErrorDetailsMIMEType().

Specified by:

writeError in interface ServiceErrorWriter

Parameters:

t - Error to write. If error is not null, it will be displayed instead of the message of this throwable.

error - Summary of the error. It may particularly contain a message different from the one of the given exception. In this case, it will displayed instead of the exception's message.

job - The job which fails.

output - Stream in which the error must be written.

Throws:

java.io.IOException - If there an error while writing the error in the given stream.

See Also:

ServiceErrorWriter.getErrorDetailsMIMEType()

getErrorDetailsMIMEType

public java.lang.String getErrorDetailsMIMEType()

Description copied from interface: ServiceErrorWriter

Get the MIME type of the error details written by ServiceErrorWriter.writeError(Throwable, ErrorSummary, UWSJob, OutputStream) in the error summary.

Important note: If NULL is returned, the MIME type will be considered as text/plain.

Specified by:

getErrorDetailsMIMEType in interface ServiceErrorWriter

Returns:

MIME type of the error details document. If NULL, it will be considered as text/plain.

See Also:

ServiceErrorWriter.writeError(Throwable, ErrorSummary, UWSJob, OutputStream)

chooseFormat

protected final java.lang.String chooseFormat(java.lang.String acceptHeader)

Parses the header "Accept", splits it in a list of MIME type and compare each one to each managed formats (managedFormats). If there is a match (not case sensitive), return the corresponding managed format immediately.

Parameters:

acceptHeader - The header item named "Accept" (which lists all expected response formats).

Returns:

The first format common to the "Accept" header and the managed formats of this writer.

formatError

protected void formatError(java.lang.String message,
                           ErrorType type,
                           int httpErrorCode,
                           java.lang.String reqID,
                           java.lang.String action,
                           JobOwner user,
                           javax.servlet.http.HttpServletResponse response,
                           java.lang.String acceptHeader)
                    throws java.io.IOException

Formats and writes the given error in the HTTP servlet response.

The format is chosen thanks to the Accept header of the HTTP request. If unknown, the HTML output is chosen.

Parameters:

message - Error message to write.

type - Type of the error: FATAL or TRANSIENT.

httpErrorCode - HTTP error code (i.e. 404, 500).

reqID - ID of the request at the origin of the specified error.

action - Action which generates the error note: displayed only if not NULL and not empty.

user - User which is at the origin of the request/action which generates the error.

response - Response in which the error must be written.

acceptHeader - Value of the header named "Accept" (which lists all allowed response format).

Throws:

java.io.IOException - If there is an error while writing the given exception.

See Also:

formatHTMLError(String, ErrorType, int, String, String, JobOwner, HttpServletResponse), formatJSONError(String, ErrorType, int, String, String, JobOwner, HttpServletResponse)

formatHTMLError

protected void formatHTMLError(java.lang.String message,
                               ErrorType type,
                               int httpErrorCode,
                               java.lang.String reqID,
                               java.lang.String action,
                               JobOwner user,
                               javax.servlet.http.HttpServletResponse response)
                        throws java.io.IOException

Formats and writes the given error in the HTTP servlet response.

A full HTML response is printed with: the HTTP error code, the error type, the name of the exception, the message and the full stack trace.

Parameters:

message - Error message to write.

type - Type of the error: FATAL or TRANSIENT.

httpErrorCode - HTTP error code (i.e. 404, 500).

reqID - ID of the request at the origin of the specified error.

action - Action which generates the error note: displayed only if not NULL and not empty.

user - User which is at the origin of the request/action which generates the error.

response - Response in which the error must be written.

Throws:

java.io.IOException - If there is an error while writing the given exception.

formatJSONError

protected void formatJSONError(java.lang.String message,
                               ErrorType type,
                               int httpErrorCode,
                               java.lang.String reqID,
                               java.lang.String action,
                               JobOwner user,
                               javax.servlet.http.HttpServletResponse response)
                        throws java.io.IOException

Formats and writes the given error in the HTTP servlet response.

A JSON response is printed with: the HTTP error code, the error type, the name of the exception, the message and the list of all causes' message.

Parameters:

message - Error message to write.

type - Type of the error: FATAL or TRANSIENT.

httpErrorCode - HTTP error code (i.e. 404, 500).

reqID - ID of the request at the origin of the specified error.

action - Action which generates the error note: displayed only if not NULL and not empty.

user - User which is at the origin of the request/action which generates the error.

response - Response in which the error must be written.

Throws:

java.io.IOException - If there is an error while writing the given exception.