Reporting Status for a Deployed Application, Host, or Engine

By default, the error or status page that tc Runtime displays when it encounters a particular HTTP status or error code (such as 404 when tc Runtime does not find a requested resource) is hard-coded. However, you might want or need to change the displayed error, for simple customization reasons or because of your organization's security requirements that dictate how error pages should work and what they should look like. This section describes how to customize what tc Runtime displays when it encounters a particular HTTP status code.

The HTTP 1.1 specification defines the HTTP status codes. The following list describes some common codes:

To customize the way tc Runtime responds when it encounters one of these codes, you add a Valve element to the server.xml configuration file whose className attribute is com.springsource.tcserver.security.StatusReportValve. The StatusReportValve has a number of other attributes that describe its behavior, as described in Attributes of the StatusReportValve.

You can specify the StatusReportValve as a direct child element of either the Host or Engine element in the server.xml file, depending on the associated Catalina container for which you want to configure the Valve. If you specify that the StatusReportValve is a direct child element of Engine, then you must explicitly disable the Valve at the Host level, using the Host attribute errorReportValveClass="".

You define how tc Runtime handles a particular HTTP status code by adding an attribute to the StatusReportValve whose name is error.XXX, where XXX is the numerical status code, such as error.404. Then set the value of this attribute in one of the following ways:

If tc Runtime encounters a status code that you have not defined in StatusReportValve using an error.XXX attribute, then tc Runtime does not act upon the status code. Additionally, if your application has already responded to the status code, then the StatusReportValve does not act upon the status code.

Once you configure your tc Runtime instance with the StatusReportValve and you start the instance, you can dynamically change the attributes of the Valve using JMX.

The following server.xml snippet shows an example of configuring a StatusReportValve for the Catalina Engine; only relevant parts of server.xml are shown (in bold):

<?xml version='1.0' encoding='utf-8'?>
<Server port="${shutdown.port}" shutdown="SHUTDOWN">

   ...
   <Service name="Catalina">
   ...

      <Engine name="Catalina" defaultHost="localhost">

        <Valve className="com.springsource.tcserver.security.StatusReportValve"
               fileEncoding="utf-8"
               contentType="text/html"
               characterEncoding="utf-8"
               zeroLengthContent="false"
               commitOnReport="true"
               cacheFiles="true"
               removeException="true"
               error.500="${catalina.base}/conf/500.html"
               error.404="${catalina.base}/conf/404.html"
               error.403="I am sorry, you do not have access"
      />

      ...
      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true" deployOnStartup="true" 
            deployXML="true" xmlValidation="false" xmlNamespaceAware="false" 
            errorReportValveClass="" >
      </Host>
     </Engine>
   </Service>
</Server>

In the preceding example, the StatusReportValve can act upon three HTTP status codes: 404, 500, and 403. When tc Runtime encounters the 404 status code, it displays the contents of the file CATALINA_BASE/conf/404.html. Similarly for status code 500, although in this case it displays the file CATALINA_BASE/conf/500.html. If tc Runtime encounters the status code 500, it displays the literal message I am sorry, you do not have access.

Note that, because the StatusReportValve is configured at the Engine level, the child Host element explicitly disables the Valve using the attribute errorReportValveClass="".

The following table describes all the attributes of the StatusReportValve.

Table 7. Attributes of the StatusReportValve

AttributeDescription
classNameSpecify the com.springsource.tcserver. security.StatusReportValve class, or a class that extends the StatusReportValve class.
fileEncodingSpecifies the encoding of the displayed static files. If you do not specify this attribute, tc Runtime uses the default platform encoding.
contentTypeSpecifies the Content-Type header for the HTTP response. Default value is text/html. See MIME Media Types for the full list.
characterEncodingSpecifies the charset parameter of the Content-Type header for the HTTP response. Default value is utf-8. See Character Sets for the full set.
zeroLengthContentIf you have set this attribute to true and the response is not committed, the Valve returns with a 0 length body. Useful for mod_jk and reverse proxy where the Web server only overrides the body if it is of 0 length (effectively, it has no body.)
commitOnReportIf you have set this attribute to true, the StatusReportValve always tries to commit the response even with a 0 length body. If you set it to false, then Valves further up the chain may change the response.
cacheFilesIf you set this attribute to true, the Valve caches the content of the static pages as java.lang.ref.WeakReference<String>. Once cached, tc Runtime makes no attempt to read the file system unless the garbage collector clears the weak references.
removeExceptionIf you set this attribute to true, the Valve removes the Globals.EXCEPTION_ATTR from the request attribute. Valves further up in the chain will no longer have access to the exception that caused the error.
error.XXXSpecifies that tc Runtime should act upon the XXX status code by displaying either the specified URI, file, or message string. See the previous discussion for details.