What s Next

Tag Definitions

In the remainder of this chapter, each of the tags defined in the Resin configuration will be outlined. An attempt has been made to keep the tags separated by their placement in the Resin configuration file and environments but realize that many of the tags can cross environments. This fact will be noted where appropriate.

Common Environment Tags

The environment defined within Resin has the following format:

Classloaders

• class-loader

• compiling-loader

• library-loader

• make-loader

• simple-loader

Clustering

• cluster

• cluster-definition

Resources

• database

• ejb-server

• env-entry

• jndi-link

• reference

• resource

• resource-ref

Logging

• log

• stderr-log

• stdout-log

Authenticator

• authenticator

Miscellaneous

• system-property

• javac

• dependency-check-interval

• character-encoding

• case-insensitive

• temp-dir

• work-dir

As stated previously, environments can appear under the tags: <resin>, <server>, <host-default>, <host> and <web-app-default>, and <web-app>. The details of each tag are discussed in the following section.

<class-loader>

Element defines a dynamic classloader for the current environment. There are four possible sub-elements: compiling-loader, library-loader, make-loader, and simple-loader. For example, the following uses the <compiling-loader> subelement.

 <class-loader>     <compiling-loader path="WEB-INF/classes"/> </class-loader> 

<compiling-loader>

Element which automatically compiles Java code into CLASS files; it has five attributes associated with it:

• path— path for the loader.

• source— directory for java source.

• args— arguments to pass to the Java compiler.

• encoding— internationalization encoding for the Java compiler.

• require-source— if true all CLASS files without Java code will be removed (default is false).

<library-loader>

Element adds JAR files found to the CLASSPATH; it has a single attribute:

• path— path where loader should look for JAR files.

<make-loader>

Element which configures a make-style loader; it is currently undefined.

<simple-loader>

Element which loads CLASS files without compiling; it has two attributes:

• path— path for the loader.

• prefix— class package prefix to filter those classes found.

<cluster>

Element defines a cluster of Resin server for load balancing - defined in Chapter 19, "Load Balancing and Reliability." There are four attributes for <cluster>:

• id— identifier for naming the cluster.

• srun— configures the srun port and protocol for cluster server.

• cluster-group— configuration for sub-clusters.

• cluster-ref— identifier of a previous defined cluster.

<cluster-definition>

This element defines a cluster to be referenced from a <cluster> element; its attributes are:

• id— identifier for naming the cluster.

• srun— configures the srun port and protocol for cluster server.

• cluster-group— configuration for sub-clusters.

Resources

Resources are components such as a database used by a web-application, host, or the server. Since they exist in an environment, each web-application can defined their own resources, including resources that override previously defined defaults.

<database>

The <database> element is primarily designed to define database pooling configurations. The defined resource is a DataSource in a JNDI context as well as ServletContext. You should place the database JDBC driver associated with the resource in either the system classpath or the /lib directory associated with the Resin server installation. You can also place the driver in the WEB-INF/lib or WEB-INF/classes directory, but this is a secondary choice.

The <database> element has numerous sub-elements for defining the database resource.

• <jndi-name>—the JNDI path relative to java:comp/env.

• <driver>—the JDBC driver class (required).

  • <url>— the location of the database as either an IP, localhost, or domain name. (Required)

  • <type>— the type of database driver being used.

• <user>—the username to use when connecting to the database. Default is an empty string.

• <password>—the password to use when connecting to the database. Default is an empty string.

• <max-connections>—the maximum number of allowed connections to the database. Default is 20.

• <max-idle-time>—the maximum amount of time an idle connection is kept open. Default is 30 seconds.

• <connection-wait-time>—the total amount of time the system waits for an idle connection to be returned to the database pool. Default is 10 minutes.

• <max-overflow-connections>—the number of possible connections to keep in an overflow state while waiting for an idle connection. This assumes the connection wait time has timed out. Default is 0.

• <ping-table>—a table to be used for a simple ping test. A value of false disables the ping test.

• <ping-on-reuse>-defines whether the database should be pinged through a connection before the connection is provided to the application. Default is false.

• <ping-on-free>—defines whether a connection should be tested before replacing the connection in the pool. Default is false.

• <ping-on-idle>—defines whether a connection should be randomly tested for a live connection. Default is false.

• <xa>—defines whether pooling is performed on the database. Values are true and false.

<ejb-server>

This element is used to define a CMP server for using EJBs under Resin. For example,

 <ejb-server jndi-name="java:comp/env/cmp">     <data-source>java:comp/env/jdbc/AccountsDB</data-source> </ejb-server> 

The attributes for the CMP server are provided using the <init-param> element. The available parameters are shown in Table 15.1.

Table 15.1: <init-param> Parameters

PARAMETER	DEFAULT	MEANING
auto-compile	true	EJB code will be automatically generated
config-directory	Directory to search for *.ejb files	WEB-INF
create-database-schema	false	if tables for entity beans aren't in the database-create them
data-source	java:comp/env/jdbc/test	JNDI name
entity-cache-size	8192	Total entity beans cached
entity-cache-timeout	inf.	Total time a bean is cached
resin-isolation	database	if database then use database's isolation, otherwise row-locking
jdbc-isolation	db default	the JDBC isolation for an update
transaction-timeout	60	timeout for a transaction
queue-connection-factory	none	JNDI name for QueueConnectionFactory
topic-connection-factory	none	JNDI name for TopicConnectionFactor

<env-entry>

When a non-servlet class needs access to a JNDI parameter, you can use <env-entry> to define the parameter. The parameters and associated values are accessible from within an application. You can define as many <env-entry> elements as needed for the environment. The element has three attributes:

• env-entry-name— an entry name defined as a JNDI path relative to java:comp/env.

• env-entry-type— the Java type of the value in the env-entry-value attribute.

• env-entry-value— the JDNI variable value.

Here's an example of a JNDI-defined variable:

 <resin>   <env-entry env-entry-name='server' env-entry-type='java.lang.String' env-entry-value='internal.company.com' /> </resin> 

This code can be used to access the variable:

 Context c = (Context) new InitialContext().lookup("java:comp/env"); String server = (String) c.lookup("server"); 

<jndi-link>

The <jndi-link> element lets Resin instantiate external EJBs defined in foreign containers. For a large number of examples, including Hessian, Burlap, WebLogic, CORBA, Inprise, Orion, jBoss, and JOnAS, check www.caucho.com/resin/ref/ejb.xtp. The attributes of <jndi-link> are as follows:

• jndi-name— the pathname for the link.

• property-file— a property used to obtain the context.

• factory— the name of the factory class used to instantiate beans.

• init-param— values used to obtain the initial context.

• foreign-name— the path used for the foreign context.

<reference>

This element is used when a JDNI ObjectFactory is needed by the server, host or web-application. For example,

 <reference>   <jndi-name>accounts/link</jndi-name>   <factory>accounts.LinkFactory</factory>   <init url="http://localhost:8080/accounts/link"/>         type="account.LinkHome"/> </reference> 

The attributes for the element are:

• jndi-name— JDBC name.

• factory— class name for Factory.

• init— initialization for the instantiation for the factory.

<resource>

This element will create a bean that can be instantiated and accessed within an application. The implementation class must be bean compliant. The beans created are stored in JDBC. For example:

 <resource name="env/login">   <type>app.RegisterForm</type>   <init>     <username>all</username>     <password>none</password>   </init> </resource> 

The attributes for the element are

• name— resource name.

• type— Bean class.

• init— Bean-style initialization.

Logging

Logging can be defined within the environment and redefined at lower levels as needed for a web-applicaton or a host.

<log>

This element defines logging using JDK 1.4 Logging. A description of the element can be found in Chapter 2 under the section "Logging in Resin."

<stderr-log>

When an application produces output using System.err, the corresponding text is directed to a system file. The < stderr_log> element has the following attributes:

• path— the path and filename for the output file.

• rollover-period— the time period that can elapse before the log file is rolled over. Values are in days (D), weeks (W), or months (M). Default is no rollover. (Optional)

• rollover-size— the maximum size of the log file before it is rolled over. Rollover occurs if the size reaches the maximum before the rollover period is reached. Default is 1 megabyte.

• timestamp— a timestamp defined in format from Table 2.3 add to each line.

The following example illustrates use of the stderr-log <host> element level. There is no <log> element. The file storecomstderr.log stores the output from stderr for all Web applications defined in the store.com host:

 <host id='store.com'> <stderr-log path='/opt/logs/storecomstderr.log' rollover-period='1W rollover-size='10M'/> </host> 

<stdout-log>

When an application produces output using System.out, the corresponding text cannot be displayed on a console (in a production setting, there is no console window). The <stdout-log> element has four attributes:

• path— the path and filename for the output file. (Required)

• rollover-period— the time period that can elapse before the log file is rolled over. Values are in days (D), weeks (W), or months (M). Default is no rollover. (Optional)

• rollover-size— the maximum size of the log file before it is rolled over. Rollover occurs if the size reaches the maximum before the rollover period is reached. Default is 1 megabyte.

• timestamp— a timestamp defined in format from Table 2.3 add to each line.

The following example illustrates the use of stdout-log. The file storecomstdout. log stores the output from stdout for all Web applications defined in the store.com host:

 <host id='store.com'> <stdout-log path='/opt/logs/storecomstdout.log' rollover-period='1W' rollover-size='10M'/> </host> 

You can also have individual files for Web applications:

 <web-app id='/storefront'> <stdout-log path='/opt/logs/storefrontstdout.log' rollover-period='1W' rollover-size='10M'/> </web-app> 

<access-log>

All requests to the Resin server can be logged at various server levels. For each request, you can create configurable output to display the information important to you. The <access-log> element can be defined at several levels of the hierarchy:

• At the <web-app> level, all requests for the designated application are output to the specified log file.

• At the <host> level, all requests for the designated host are output to the specified log file if <access-log> isn't defined at the <web-app> level.

• At the <http-server> level, all requests for the designated host are output to the specified log file if <access-log> isn't defined at the <web-app> or <host> level.

The <access-log> element has six attributes:

• path— defines the path and filename for the log file. The log is relative to $RESIN_HOME. (Required)

• format— defines the format of the output to the log. The individual values are shown after this list and follow the Apache standard. Default string is "%h %1 %u %t \"%r\" %>s %b \"%{Referer)i\" \"%{User-Agent}i\"". (Required)

• rollover-period— the time period that can elapse before the log file is rolled over. Values are in days (D), weeks (W), or months (M). Default is no rollover. (Optional)

• rollover-size— the maximum size of the log file before it is rolled over. Rollover occurs if the size reaches the maximum before the rollover period is reached. Default is 1 megabyte.

• bean-class— allows a custom developer-created class for logging. The class must implement AbstractAccessLog. No default.

• init— parameters are passed to the log as bean parameters and are accessible from a class that implements AbstractAccessLog.

• archive-format— name used for archive files.

The format attribute defines how each request appears in the log file. Before we show you all the options, consider the following example of an access-log definition for all pages in a storefront Web application:

 <web-app id='\storefront'>   <access-log id='e:/log/access.log' rollover-period='10D' format='%h %r"/> </web-app> 

The output is stored in a file called access.log in a /log directory on the E: drive. Each request from a client browser records the remote IP address and the requested URL. The format values are as follows:

• %b—Result content length.

• %h—Remote IP address.

• %{X}I—Request header X.

• %{X}o—Response header X.

• %{X}c—Cookie value X.

• %n—Request attribute.

• %r-Request URL.

• %s—Status code.

• %{X}t—Request date with optional time format string.

• %T—Time of request in seconds.

• %u—Remote user.

• %U—RequestedURI.

Authenticator

Authentication be defined globally for the server or host and redefined as needed by a web-application.

<authenticator>

This element will define a authentication resource in the current environment. The authenticator uses a class that extends com.caucho.server.secu-rity. AbstractAuthenticator. For example:

 <authenticator> <jndi-name>accounts/login</jndi-name> <class>AccountAuthenticator</class> <init>   <configtype>5</configtype> </init> 

The attribute for the element are

• name— JDBC name for the authenticator - default is /caucho/auth.

• class— class for the authenticator.

• init— Javabean style configuration.

Miscellaneous

For following elements aren't specific to any host or application but provide miscellaneous information to the server.

<system-property>

The Resin server lets you set system properties in the configuration file using the <system-property> element:

 <resin>   <system-property titleclr='red' />   <system-property maxConn='60' /> </resin> 

<javac>

The most important external application used by the Resin server is a Java compiler. Each time a servlet or JSP is accessed, the Java compiler may need to compile the code. Every code change definitely invokes the compiler. In a development environment, the compiler associated with the Java Development Kit (JDK) is perfectly suitable to the task. However, in a production situation, we recommend a faster compiler. One of the best Java compilers is IBM's Jikes (www-124.ibm.com/developerworks/oss/jikes/); if you install this compiler, you should use it instead of the JDK compiler.

By default, the Resin server uses the internal compiler found in the JDK, as noted by the <javac> element provided in the resin.conf file:

 <javac compiler="internal" compiler-args=""/> 

The <java> element is found in the <caucho.com> root element and has three attributes:

• compiler— defines the path to a specific Java compiler to be used with the system or internal for the JDK compiler. Default is internal.

• args— compiler arguments to be passed through to the compiler as needed. No default.

• encoding— the character encoding used. No default.

• max-compile-time— the total time the Resin server will allow for the compiling of an application. Default is 30 seconds.

Here's an example of a <java> configuration using Jikes:

 <resin>   <java compiler='e:/jikes/jikes' compiler-args='-g' max-compile- time='60' /> </resin> 

<dependency-check-interval>

This element defines how often the environment contexts will be checked for changes. The default is every 2 seconds. For deployment, use a larger value like 60s or 1h.

<case-insensitive>

If you have worked with both UNIX and Windows, you know that UNIX is case-sensitive and Windows is not. For both the <servlet-mapping> and <filter-mapping> elements, matches need to be made on URLs. The Resin server can treat the matching in a case-sensitive or case-insensitive manner. The default is true for Windows and false for Unix. These defaults can be changed as needed:

 <web-app>   <case-sensitive>true</case-sensitive> </web-app> 

<temp-dir>

A temporary directory is available to all Web applications and associated with the variable javax.servlet.context.tempdir. The default value for the temporary directory is WEB-INF/tmp. You can change the directory for each Web application using this format:

 <web-app>   <temp-dir>e:/$app-dir/app/temp</tmp-dir> </web-app> 

In a servlet, you can obtain the temporary directory using the following code:

 File dir = (File) getServletContext().getAttribute("javax.servlet.con- text.tempdir"); 

<work-dir>

All Web applications have an associated work directory for placement of server-compiled code. The default directory is WEB-INF/work. To change the directory, use the <work-dir> element:

 <web-app>   <work-dir>e:/$app-dir/app/work</tmp-dir> </web-app> 

Web-App Tags

Web applications are key to the use of Resin; therefore, there are quite a few tags available to configure their operation. The tags are divided into two areas: basic configuration and servlet definitions.

Basic Configuration

<web-app-default>

This element defines specific elements that are designed to be used for all Web applications. All of the elements defined earlier for the <web-app> can be used within this element. The <web-app-default> element can be used within <server>, <host-default>, and <host>.

<web-app-deploy>

This element is used to define the directory where a WAR file is expanded. The attributes available are:

• path— path to the webapp directory.

• url-prefix— prefix to add to all expanded webapps.

• expand-path— directory where WAR files are expanded.

• lazy-init— if true, then Web applications should be initialized only when first requested by a user. Default is false.

<web-app>

This element defines a new web-application to be used in the system. The sub-element can include those for an environment listed above, as well as the elements under the section "Servlet 2.4 Definitions" below.

<cache-mapping>

When you set up a cache on the Resin server, specific pages in a Web application can be assigned different cache intervals. Basically, the <cache-mapping> element enables the developer or system administrator to control an application's pages in the cache for better management. The elements attributes are:

• url-pattern— a pattern for matching a specific URL.

• url-regexp— a regular expression for matching a URL.

• expires— a time interval representing the number of seconds a page lives in the cache. The value in the attribute can use the following time values: seconds (S), minutes (M), hours (H), and days (D). There is currently no default time for the expires attribute. Defaults to seconds.

The following example shows how to use the <cache-mapping> element to keep pages in the cache for different periods of time:

 <web-app id='\store'>   <cache-mapping     url-pattern='\storefront\*.jsp'     expires='120S' />   <cache-mapping     url-pattern='\storefront\images\*'     expires='15M' /> </web-app> 

<path-mapping>

The <path-mapping> element maps URL patterns to a real path value. The attributes in the element are:

• url-pattern— the string used to match a URL.

• url-regexp— the regular expression to match a URL.

• real-path— the real path. Can use variables from a regular expression.

Here's an example:

 <web-app id='/store'>   <path-mapping     url-pattern='/storefront'     real-path='e:/webs/store' /> </web-app> 

<strict-mapping >

By default, the Resin server lets a <servlet-mapping> violate the Servlet 2.4 specification by allowing .jsp extension paths like /store/myjsp/ storefront.jsp. To ensure strict Servlet 2.4 <servlet-mapping> elements, set the value to true. For example:

 <web-app>   <strict-mapping>true</stict-mapping> </web-app> 

Servlet 2.4 Definitions

<description>

This tag is currently not defined.

<display-name>

This tag is currently not defined.

<distributable>

This tag is currently not defined.

<context-param>

When you need to define variables for a Web application at the server level, you can put them in the resin.conf or web.xml file using <context-param>. Any number of variables may be added to the configuration files. This element has two attributes:

• param-name— the name of the variable.

• param-value— the value of the variable.

There are two ways to add the <context-param> element:

 <web-app id='/storefront'>   <context-param max='50' />   <context-param>     <param-name>title</param-name>     <param-value>My New Store</param-value>   </context-param> </web-app> 

<filter>

When you need to define a filter, you can use the <filter> element to create an alias commonly used in a <filter-mapping>. The <filter> element associates a filter class with a common alias name. The attributes available in the <filter> element are as follows:

• filter-name— the filter name or alias.

• filter-class— the actual filter class to associated with the alias name.

• init-param— initialization parameters for the filter class.

As example of using the <filter> element appears in the <filter-mapping> section that follows.

<filter-mapping>

The <filter-mapping> element is designed to match a URL-pattern and a filter. When a URL is found that matches the URL pattern, the listed alias is matched with a filter class and the filter is applied. The <filter-mapping> element contains six attributes:

• url-pattern— a pattern for matching a specific URL.

• url-regexp— a regular expression for matching a URL.

• filter-name— the servlet name to match, thus combining the functionality of the filter with the <servlet-mapping> element.

• dispatcher— Multiple <dispatcher> tags are allowed. REQUEST, INCLUDE, FORWARD, and ERROR are defined. If no <dispatcher> is defined, the filter-mapping uses REQUEST.

• filter-name— either an alias defined in a <filter> element or a specific servlet class.

Here's an example of using the <filter-mapping> element:

 <web-app>   <filter     filter-name='product-filter'     filter-class='store.product-filter' />   <filter-mapping     url-pattern='/products/*'     filter-name='product-filter' /> </web-app> 

<listener>

This tag is currently not defined.

<servlet>

The Resin server allows a servlet to be mapped from a URL pattern to a specific servlet. For example, the string /storefront.html should be mapped to a servlet called storefront, which in turn represents a servlet class store.store-front. The <servlet> element is used to associate a servlet name with a specific servlet class called an alias. The attributes for <servlet> are:

• servlet-name— the servlet name.

• servlet-class— the name of the servlet's class. Default is the servlet-name value.

• init-param— necessary initialization parameters for the servlet.

• load-on-startup— defines whether the servlet should be instantiated and initialized upon server start.

• run-at— determines when the server should be automatically executed. Examples include 3:00, 3:15, and so on.

Here's an example of an alias for a time servlet that runs at 1:00 a.m. each morning:

 <web-app id='/utilities''>   <servlet     servlet-name='time'     servlet-class='time.utilities.setup'     run-at='1:00'   /> </web-app> 

<servlet-mapping>

As mentioned earlier, you can map a URL to a servlet using the <servlet-mapping> element. This means you can define a URL pattern like \store* to execute a servlet. The element has four attributes:

• servlet-name— name of servlet.

• url-pattern— the url pattern to match.

• url-regexp— the url pattern to match based on a regular expression.

• servlet-name— the servlet name can using replacement vars or the name.

For example:

 <web-app>   <servlet     servlet-name='storefront'     servlet-class='store.storefront'     run-at='1:00'   />   <servlet-mapping>     <url-pattern>\store*</url-pattern>     <servlet-name>storefront</servlet-name>   </servlet-mapping> <web-app> 

You can combine the <servlet> and <servlet-mapping> elements into one. Here's an example:

 <web-app>   <servlet-mapping     url-pattern='\store*'     servlet-class='store.storefront' /> <web-app> 

<session-config>

When a Web application uses sessions, you can use the <session-config> element to configure how the sessions act and maintain themselves. The attributes available in the element are as follows:

• session-timeout— the length of time before a session times out. Default is 30 minutes.

• session-max— the maximum number of active sessions allowed. Default is 4096.

• enable-cookies— defines whether cookies are used with sessions. Default is true.

• enable-url-rewriting— defines whether URL rewriting may occur. Set enable-cookies to false to force URL rewriting. Default is true.

• cookie-version— the current cookie spec used for sessions. Default is 1.0.

• cookie-domain— the cookie domain. Default is none.

• cookie-max-age— the maximum age allowed for session cookies. Default is none.

• cookie-length— the maximum length of a cookie. Default is integer.MAX_VALUE.

• file-store— defines whether a file store should be used for sessions.

• jdbc-store— defines whether a JDBC store should be used for sessions.

• tcp-store— defines whether a distributed ring should be used for sessions.

• always-load-session— defines whether session data should be reloaded upon each request. Default is false.

• always-save-session— defines whether session data should be saved upon each request. Default is false.

• save-on-shutdown— defines whether session data should be saved only on shutdown. Default is false.

• reuse-session-id— defines whether a session id should be reused regardless of whether the session has timed out. Default is true.

• ignore-serialization-errors— defines whether objects that don't implement java.io.Serializable should be ignored when a session is saved. Default is false.

• persistant-path— TBD.

• cluster-store— if persistent sessions are used, the cluster will be used for storage.

• invalidate-after-listener— TBD.

<mime-mapping>

Most of the popular file extensions have automatic mime-types associated with them, as found in com.caucho.server.http.Application. If you have specific file extensions that need to be associated by the server, use the <mime-mapping> element. The element has two attributes:

• extension— a url to match.

• mime-type— the mime-type to associate with the specific extension.

As an example, the following element associates the extension .xxm to an html mime-type:

 <web-app>   <mime-mapping     extension='.xxm'     mime-type='text/html' /> </web-app> 

<welcome-file-list>

The <welcome-file-list> element defines the pages that can be used when the user doesn't specify an actual filename. A user typically enters the URL www.mycompany.com and expects a page to be returned. By default, the Resin server attempts to find three different pages: index.xtp, index.jsp, or index.html. If none of these files are found, a 404 error is returned. This element enables you to define other pages as defaults using one or more <welcome-file> elements. Here's an example:

 <web-app id='/storefront'>  <welcome-file-list>   <welcome-file>store.html</welcome-file>   <welcome-file>store.jsp</welcome-file>   <welcome-file>storefront.jsp</welcome-file>  </welcome-file-list> </web-app> 

The files can also be listed as follows:

 <web-app id='/storefront'>   <welcome-file-list>store.html, store.jsp, storefront.jsp /> </web-app> 

<error-page>

As you've seen several times in previous chapters, the default behavior for Resin as well as other application and Web servers when an error occurs in a page request is to display a generic 404- or 500-type error. The error information may include a stack dump in the case of servlets. Although errors do occur, you don't want to scare users with such a dull error presentation. Instead, you can provide a page that looks like the rest of the site and offers users help with the error. The <error-page> element allows this type of flexibility. The attributes in the element are as follows:

• location— defines the path and filename of the error page.

• exception-type— causes the location page to be executed when the specified exception is thrown.

• error-code— causes the location page to be executed when the specified HTTP status code is found.

The following example shows how to catch some of the more common errors:

 <web-app id='/'>     <error-page      error-code='404'            location='/errorpages/file_not_found.html'/>     <error-page             exception-type='java.lang.NullPointerException'            location='/errorpages/nullpointer.html'/> </web-app> 

<jsp-config>

This tag is currently not defined.

<resource-env-ref>

This tag is currently not defined.

<message-destination-ref>

This tag is currently not defined.

<resource-ref>

This tag is currently not defined.

<security-constraint>

The developer of a site doesn't necessarily have to use authentication to secure areas of the Web site; you can use the <security-constraint> element. The element includes several subelements:

• <web-resource-collection>—Defines which areas of a site have a restriction. This element has two attributes:

  • url-pattern— the directory and possible files to be restricted.

  • method— HTTP methods to be restricted.

• <user-data-constraint>—defines the transports that must be used to access the restricted files. It has one attribute:

  • transport-guarantee— the transport type: NONE, INTEGRAL, or CONFIDENTIAL. SSL requires the CONFIDENTIAL value.

• <auth-constraint>—used when authenticated users have a role. The single attribute is as follows:

  • role-name— the role that has access to the restricted area.

• <ip-constraint>—the IP addresses that can access the restricted areas.

• <constraint>—defines a custom constrait. The attributes are:

  • class-name— a class that extends com.caucho.http.security.AbstractConstraint.

  • init-param— initialization parameters.

<security-role>

This tag is currently not defined.

<env-entry>

This tag is currently not defined.

<ejb-ref>

This tag is currently not defined.

<ejb-local-ref>

This tag is currently not defined.

<message-destination>

This tag is currently not defined.

<locale-encoding-mapping-list>

This tag is currently not defined.

<deployment-extension>

This tag is currently not defined.

Application and Server Tags

<web-app-deploy>

When the WAR files are expanded, they are expanded into the <web-app-deploy> directory. If you don't want the expanded WARs in the same directory as the WARs themselves, use the <war-expand-dir> element to define where they should be expanded. Just like the <web-app-deploy> element, the <war-expand-dir> element is relative to $RESIN_HOME.

<character-encoding>

The default character encoding for Resin is ISO-8859-1. To change the encoding, use the <character-encoding> element:

 <web-app>   <character-encoding>UTF-16</character-encoding> </web-app> 

<dependency-check-interval>

The Resin server automatically checks to determine whether any configuration file has changed on the server and it should force a reload. The default value is 2 seconds; you should set this value as low as possible for development servers. When a server is moved to a production phase, the interval should be much higher because of the overhead associated with checking for new code. You can change the value using the <dependency-check-interval> element:

 <web-app>   <dependency-check-interval>2D</dependency-check-interval> </web-app> 

The interval value can use seconds (S), minutes (M), or days (D).

<taglib>

If you have a tab library for a Web application, you can use the <taglib> element to configure the library. The element attributes are:

• taglib-uri— the matching URI for the tag library.

• taglib-location— the path to the actual tag library, relative to classpath; typically the tag library is found in WEB-INF/classes.

Here's an example:

 <web-app>   <taglib     taglib-uri-'/storefront/store'     taglib-location='/store.tld'/> </web-app> 

<description>

This element describes the Web application and current has no functionality. The following example uses both <display-name> and <description>:

 <web-app>   <display-name>My Store Front</display-name> <description>This is the store front servlet</description> </web-app> 

<multipart-form>

In order for Resin to handle multipart forms and file uploads, you must use the <multipart-form> element to enable support. By default, the server does not support multipart forms and file uploads. If the upload limit is exceeded or uploads are disabled, a caucho.multipart.form.error exception is thrown. The element has two attributes:

• enable— defines whether support is available. A value of true indicates support.

• upload-max— the maximum size of an upload in kilobytes. Default is no limit.

For example, support can be enabled with the following element:

 <web-app>   <multipart-form     enable='true'     upload-max='1024' /> </web-app> 

<browser-mapping>

As you know, not all browsers are created equal. If you determine that some of your users are using a browser that needs HTTP/1.0 tags instead of 1.2 or later, you can list these browsers as troublesome using the <browser-mapping> element. The attributes available in this element are:

• regexp— a regular expression to match the User-Agent HTTP header.

• force10— if found in the element, forces HTTP/1.0.

There is no default <browser-mapping>, but the default resin.conf file includes four commented elements:

 <browser-mapping regexp="MSIE 4\.0b2" force10/> <browser-mapping regexp="RealPlayer 4\.0" force10/> <browser-mapping regexp="Java/l\\.0" force10/> <browser-mapping regexp="JDK/1\\.0" force10/> 

<lazy-init>

Resin's default behavior is to load all Web application when the server starts and automatically execute those servlets whose <load-on-init> elements are defined. Here's an example:

 <web-app>   <lazy-init>true</lazy-init> </web-app> 

<app-dir>

By default, a Web application has a home directory with the same name as the <web-app> element's id attribute. If you need to change the application directory, use the <app-dir> element. The attributes for the element are as follows:

• id— the prefix from the URL matching the Web application.

• url-regexp— a regular expression to match a URL.

• app-dir— default is a subdirectory using the id attribute. The root directory for the Web application.

For example:

 <host id='company.com'>   <web-app     id='/store'     app-dir='/usr/home/webs/store' /> </host> 

<secure>

If a Web application can only be accessed from a secure connection, you should set the <secure> element to true. For example:

 <web-app>   <secure>true</secure> </web-app> 

<regexp>

The Resin server allows the use of regular expressions to match information passed to the application. One such use is the ID of a <host> element. For example:

 <host   regexp='([^ /]*).company.com'   doc-dir='e:/pages/$1/docs' /> 

The regular expressions are based on Per15 with 16-bit strings. You can find more information at www.caucho.com/resin/jsref/regexp.xtp.

<url-character-encoding>

You can use the <url-character-encoding> element to specify the character encoding used by the server to decode an incoming URL. The default is utf-8. To change the encoding as needed, use the element as follows:

 <host>   <url-character-encoding>UTF-16</url-character-encoding> </host> 

<host>

The <host> element defines specific hosts in an <http-server> element. When a request is made on the server, a match is attempted with all the <host> elements. If a match is found, the configuration for the matched <host> is used. Default is the <server> <root-directory> value. The attributes of the <host> element are:

• id— the host name. (Required)

• regexp— a regular expression to be used to match an incoming host.

• root-directory— defines the root directory for this host.

• document-directory— defines the document directory for this host.

If a regular expression is used, you can use replacement variables. Here's an example:

 <server>   <host-name="www.mycompany.com, mycompany.com">   <root-directory>hosts/mycompany</root-directory> </server> 

<port>

This element specifies the port the HTTP or srun should listen to. Most HTTP Web servers listen to port 80.

<http>

The Resin server requires the definition of a port for HTTP requests and potentially a port for secure requests. The <http> element handles the definition using a number of attributes:

• id—the name of the identifier.

• host—the name of the host listening for requests; not needed if local-host. Defaults to all interfaces.

• port—the port the server should listen to for requests.

• openssl and jsse-ssl—defines option for openssl or jsse-ssl.

  • ssl— defines whether SSL is enabled.

  • ss12— defines whether SSLv2 is enabled.

  • ssl3— defines whether SSLv3 is enabled.

  • tls1— defines whether TLSv1 is enabled.

  • key-store-type— defines the JSSE key store type. Applies only to jsse-ssl. Default is jks.

  • key-store-file— defines the JSSE file with certificates. Applies only to jsse-ssl.

  • password— defines the password needed to access certificates. Also defines an OpenSSL password needed for the key file.

  • certificate-chain-file— defines an OpenSSL certificate chain.

  • certificate-file— defines an OpenSSL certificate.

  • certificate-key-file— defines an OpenSSL key file.

  • crypto-device— defines the OpenSSL engine.

<srun>

You can designate multiple machines for srun load balancing. To add machines, use multiple <srun> elements. The attributes defined in the element are:

• id— the srun identifier.

• host— the host when srun is available.

• port— the port for the specified host.

• backup— backup server definition.

For examples of <srun> see Chapter 19, "Load Balancing and Reliability."

<thread-max>

As requests are sent to the Resin server, threads are spawned to handle the processing. The default number of threads for the server is 200. You can change the thread count with the <thread-max> element:

 <server>   <thread-max>500</thread-max> <server> 

<thread-min>

Just as there is a maximum number of processing threads, there is also a minimum. The default is five threads, but you can change this value with the <thread-min> element:

 <server>   <thread-min>50</thread-min> </server> 

<thread-keepalive>

In situations where an external Web server is used to handle page requests and Resin is used to handle JSPs/servlets, you must use a socket connection to pass information between the applications. These sockets are called keepalive connections. Resin attempts to reuse the connections as much as possible. The element <thread-keepalive> determines the total number of threads that can be used in the connections. The default is 100; you can change the value as follows:

 <server>   <thread-keepalive>500</thread-keepalive> </server> 

<request-timeout>

The server waits a default time of 30 seconds for a request. Once the timeout has expired, the request is interrupted. To change the request timeout, use the <request-timeout> element:

 <server>   <request-timeout>120s</request-timeout> </server> 

<live-time>

When the Resin server is in a load-balancing situation, the <live-time> element determines how long an idle srun connection remains open. When the timeout expires (the default is 10 seconds), the connection is closed. The <live-time> value must be less than <request-timeout>. Here's an example:

 <server>      <live-time>60s</live-time> </server> 

<dead-time>

As discussed in Chapter 19, "Load Balancing and Reliability," once a server is determined to be dead, the other servers wait a default of five seconds before retrying the potentially dead server. This value can be changed with the <dead-time> element:

 <serve>   <dead-time>10s</dead-time> </server> 

<connect-timeout>

The Resin server waits a default time period of 30 seconds for a connection between the Web server and the Resin srun. If the timeout is exceeded, the server gives up on the connection. You can change the timeout with the <connect-timeout> element:

 <http-server>   <connect-timeout>60s</connect-timeout> </http-server> 

<timeout-interval>

The Resin server initiates a disconnection from the client after a default time of 60 seconds. You can use the <timeout-interval> element to change the timeout:

 <server>   <timeout-interval>120</timeout-interval> </server> 

<accept-buffer-size>

The Resin server listens for client connections on the designated port, such as 80 or 8080. Once a connection is made, an internal socket port is assigned to the remote connection. The server defaults to 256 sockets in the accept buffer the server uses to assign remote connections. To change the number of sockets, use the <accept-buffer-size> element:

 <server>   <accept-buffer-size>1024</accept-buffer-size> <server> 

<listen>

When the Resin server launches, a listen method call is made. The default value for the total number of listening threads is 5. You can change this default with the <listen> element:

 <server>   <listen>25</listen> </server> 

The higher the number of listen threads, the greater the required system resources. It is recommended that you change the value in small increments and gauge performance.

<cache>

For performance purposes, you should configure the Resin server to use a cache. The Resin cache acts as a high-performance proxy cache; it will help with both static and dynamic pages. The cache is not activated by default; a specific <cache> element must be located in <http-server>. The cache uses both memory and the filesystem to keep cached pages.

The attributes available in the <cache> element are as follows:

• path— the file directory where cached pages not in memory should be stored. Default is <installation dir>/cache.

• entries— the total number of entries allowed in the cache also contingent on the size of the cache. Default is 16386.

• enable— defines whether the cache is enabled. Default is true.

• memory-size— size of memory to use.

• disk-size— size of disk to use.

The default resin.conf configuration file defines the <cache> element as follows:

   <cache dir='cache' size='1024' entries='8192'/> 

<ping>

One of the hallmarks of a successful site or Web application is uptime. You can use external monitoring packages or the Resin server to monitor site code. The <ping> element defines a set of URLs and conditions for checking on a site. The code behind <ping> is designed to ping the URLs and, after a set number of attempts, bring down the Resin server. In a production setting, the OS uses a server or a script to restart the server automatically. The ping code is executed in a separate thread from Resin, but it remains in the same Java Virtual Machine so problems with the VM will not be detected. The attributes of the <ping> element are:

• url— the URL that should be pinged. (Required)

• sleep-time— the time to wait between pings. Default is 15 minutes.

• retry-count— the number of retries before restarting Resin. Default is 3.

• retry-time— the length of time to wait before attempting a new ping after a failed ping. Default is 1 second.

• class-name— a custom ping class. Default is com.caucho.http.admin.PingThread.

Here's an example of using <ping>:

 <server>   <ping>     <url>http://localhost:80/store/storefront.jsp</url>     <retry-count>2</retry-count>     <retry-time>15s</retry-time>     <sleep-time>30m</sleep-time>   </ping> </server> 

You can write a custom ping class by extending com.caucho.http.admin. PingThread. One such extension is called PingMailer; it sends an email when a ping test has failed. The following attributes are available in PingMailer, in addition to those already listed:

• mail-to— the email address of the recipient. (Required)

• mail-from— the sender of the email. Default is resin process user.

• mail-subject— the subject text of the email. Default is "Resin ping has failed."

Here's an example of using PingMailer:

 <server>   <ping>     <url>http://localhost:80/store/storefront.jsp</url>     <retry-count>2</retry-count>     <retry-time>15s</retry-time>     <sleep-time>30m</sleep-time>     <class-name>com.caucho.http.admin.PingMailer</class-name>     <mail-to>[e-mail]</mail-to>   </ping> </server> 

<ignore-client-disconnect>

A user of a Web application isn't required to complete transactions or continue viewing your site if a request is taking too long. A user's Internet connection may also be broken using a request. In these cases, you can make the Resin server throw an exception (ClientDisconnectionException) when the client disconnects. The default value is false, which means client disconnect exceptions are not ignored. You can change this value using <ignore-client-disconnect>:

 < server>   <ignore-client-disconnect>true</ignore-client-disconnect> </ server> 

<forbid-host>

The Resin server can deny access to a list of IP addresses using the <forbid-host> element. The code for forbid is contained in com.caucho.http.security. ForbidHost and has a JNDI value of java:comp/env.caucho/forbid-host. Here's an example that uses the element:

 < server>   <forbid-host>145.4.3.2</forbid-host>   <forbid-host>134.2.33.167</forbid-host> </ server> 

<session-url-prefix>

When Resin uses sessions, a URL prefix is used for url-rewriting. The default string is ;jessionid=. You can change this string using the <session-url-prefix> element:

 <server>   <session-url-prefix>;resinsession=</session-url-prefix> </ server> 

<alternate-session-url-prefix>

When sessions are used with JSPs, you can define an alternate prefix with <alternate-session-url-prefix>:

 <server>   <alternate-session-url-prefix>;J=</alternate-session-url-prefix> </server> 

<sticky-sessions>

If your load-balancing solution needs sticky sessions, you can enable them with the <sticky-sessions> element. You can find more information about load balancing in Chapter 19, "Load Balancing and Reliablility." An example of using the element is as follows:

 <server>   <sticky-sessions>true</sticky-sessions> </server> 

<global-system-properties>

When you use the <system-property> element to provide property values to the Resin-hosted Web applications, the server automatically keeps the properties separate as long as the <system-property> elements appear in individual <host> elements. To turn off this default behavior, use the <global-system-properties> element:

 <server>   <global-system-properties>true</global-system-properties> </server> 

<session-cookie>

The Resin server uses cookies for authentication and session information. The default cookie name is JSESSIONID. To change the cookie, use the <session-cookie> element:

 <server>   <session-cookie>RESINCOOKIE</session-cookie> </server> 

<url-length-max>

When the Resin server receives an HTTP URL, it is checked against a default maximum length value of 8192. If the URL length is greater than 8192, the browser is passed an error. If you need URLs that are longer than 8192 characters, you can use the <url-length-max> element:

 <server>   <url-length-max>16384</url-length-max> </server> 

<jsp> Configuration Elements

The Resin server handles all types of files, including the Resin-specific XTP and servlets. In addition, Resin handles the serving, compiling, and execution of JSPs. You can set a number of configuration options specifically for these pages. All the options are defined under the <jsp> element in the <caucho.com> root.

A total of 11 attributes can be set in the <jsp> element:

• auto-compile— defines whether changes made to files with a .jsp extension should be automatically recompiled when the server is executing. Default is true.

• disable-init-log— when a <log> element is defined for JSP logging, this option (when false) disables the logging of init() and destroy() methods on JSP objects. This keeps the log from growing too quickly and eliminates garbage in the log. Default is false.

• jsp-update-interval— the amount of time the server waits before checking whether a JSP file has been modified. Default is 2 seconds.

• jsp-max— the total number of active JSP pages. Default is 1024.

• precompile— defines where the server should precompile JSPs during startup. Default is true.

• require-source— before a JSP is executed, defines whether the server should check to see if the original source file is available. If not, the compiled JSP is not executed. Default is false.

• recompile-on-error— defines whether the server recompiles a JSP if it has previously thrown a java.lang.Error exception. Default is false.

• recycle-tags— determines whether the server recycles tags as defined by the JSP 2.0 specification. Default is true.

• session— defines whether sessions are activated. Default is true.

• static-encoding— defines whether the server precompiles character encoding. If true, auto-compile is forced true. Default is true.

• velocity— defines whether Velocity-style syntax can be used in a JSP file. Default is true.

The default <jsp> element in resin.conf is as follows:

 <jsp   precompile='true'   static-encoding='true'   recompile-on-error='true'/> 

You can change the attributes in the default <jsp> as needed, and add new attributes.