ErrorFilter

The task of the ErrorFilter is to handle the occurrence of servlet errors. The various Dump parameters are not recommended due to performance considerations.

Classname

 ch::nevis::isiweb4::filter::error::ErrorFilter

Library

libErrorFilter.so.1

Configuration

StatusCode

Type: Newline-separated list of error mapping rules
Usage Constraints: required, conditional
Supported pragmas: continue (default), break
Syntax: <statuscode>:<resource>:<uri>[:<header-action>][:<status-code-action>]

This attribute defines a whitespace-separated list of error mapping rules. HTTP status codes are mapped to locations that have to be accessible by a configured resource. An error mapping rule has the following format:

• <statuscode>: A valid HTTP status code. Rules mapped to status code "200" will be ignored.
• <resource>:<uri>: The resource and its location, which will handle the error mapping. Allows the following options:
  • servlet:uri: Refers to the name of a configured servlet and the corresponding URI.
  • file:path: Refers to a file in the docBase directory with the specified path. The file extension determines the Content-Type of the response, see Static Content.
  • redirect:location: Sends a redirect response to the specified location.
• <header-action>: Defines what should be done with the headers received together with the error. This configuration attribute is optional. The supported values are:
  • keep-header: All the headers from the error message are left unchanged and sent to the frontend.
  • reset-header: All the headers are removed from the response. This is the default behavior if not configured otherwise.
• <status-code-action>: Defines what to do with the original status code. If the resource is a redirect (setting redirect:location), no status code action is supported.
  • reset-status-code: The status code of the servlet will be returned to the frontend. This is the default if the resource is a servlet (setting servlet:uri).
  • keep-status-code: The status code of the backend will be returned to the frontend. This is the default if the resource is a file (setting file:path).
  • <status-code>: A status code (100-599) that will be returned to the frontend. This feature can be used to overwrite specific error codes.

CheckAcceptHeader

Type: Boolean
Usage Constraints: optional
Default: false

Checks if the client can accept the content type of the error page using the Accept header, or if a plain error response must be sent instead. This permits the configuration of User-Agent specific ErrorFilter with identical mappings.

If CheckAcceptHeader is true, the quality of the Accept header is checked as well. If the quality of the backend's mime type is bigger than the one of the error page, the backend's error page will be submitted.

PlaceHolders

Type: newline-separated list of placeholders
Usage Constraints: optional
Syntax: <holderName>:TRANSFER_ID or TIMESTAMP

These placeholders are replaced with the transfer ID or a timestamp (time at which the error occurred) if found in the error page. The replacement is always performed for file resources. See PlaceHolders.ContentTypes for responses provided by a servlet. The placeholder <holderName> is case-sensitive.

PlaceHolders.ContentTypes

Type: newline-separated list of regular expressions
Usage Constraints: optional
Default:

^text/
^application/json

When the resource for an error status code is a servlet, the PlaceHolders are replaced if the Content-Type of the response matches one of the configured regular expressions.

KeepHeaders

Type: newline-separated list of header names
Usage Constraints: optional

The configured response headers are not removed in case of an error, regardless of the <header-action>, as described in the StatusCode parameter.

The following parameters are not recommended because of performance reasons.

DumpFile

Type: Boolean
Usage Constraints: optional
Default: false

If set to "true", the original response (which is overwritten by this ErrorFilter) will be dumped to a file.

DumpFileName

Type: Enum
Possible values: TIMESTAMP, TRANSFER_ID
Usage Constraints: optional

Name of the file used to dump the response. Either a timestamp (together with the pid and thread ID for uniqueness) or the transferId can be used. In case it is used when dumping directly in a file, it will be used as filename. If a servlet is used to upload the error page, the filename can be delegated in a header.

DumpDirectory

Type: String
Usage Constraints: optional

Directory where the error pages will be dumped. The administrator must monitor the size of the directory, otherwise the disk can be filled with error pages dumps.

DumpServlet

Type: String
Usage Constraints: optional
Syntax: <ServletName>[:<uripath>]

Name of a HttpConnectorServlet used to upload the error page.

DumpServlet.StatusHeaderName

Type: String
Usage Constraints: optional

The name of the header used to inform the dump back end of the received error code.

DumpHeaderName

Type: String
Usage Constraints: optional

The name of the header used to inform the dump server of the filename (transferId or timestamp, see DumpFileName) to use. If not configured, the backend will not be informed of the filename.

Example configuration

The configuration parameter StatusCode allows mapping a specific error code to an error source (servlet, file or redirect) and location as the following example shows:

<init-param>
    <param-name>StatusCode</param-name>
    <param-value>
          400:UnsecureProxyConnector:/error_pages/400.html
          401:UnsecureProxyConnector:/error_pages/401.html
          500:file:/error_filter/server_error.html
          401:redirect:/login/
    </param-value>
    <description>errorCode:servlet:location ...</description>
</init-param>

To use the parameter PlaceHolders, configure the ErrorFilter as follows:

<filter>
     <filter-name>PlaceHolderErrorFilter</filter-name>
     <filter-class>ch::nevis::isiweb4::filter::error::ErrorFilter</filter-class>
     <init-param>
         <param-name>StatusCode</param-name>
         <param-value>
             401:file:/error.html
         </param-value>
     </init-param>
     <init-param>
         <param-name>PlaceHolders</param-name>
         <param-value>
             TransferIdHolder:TRANSFER_ID
             TimestampHolder:TIMESTAMP
         </param-value>
     </init-param>
</filter>

In the file error.html, place the parameter PlaceHolders as follows:

An error occured at TimestampHolder.

The word TimestampHolder will then be replaced with the current timestamp.