caucho
Resin
FAQ
Reference Guide
JavaDoc
Demo
Tutorial

Getting Started
Configuration
EJB
Topics
JSP
XTP/XSL

Basic Config
Resin Config
HTTP Config
App Config
Servlet Config
SSL
Login Config
Taglib Config
Summary
 

HTTP Config
Configuration
Servlet Config

HTTP configuration follows the Servlet 2.2 deployment descriptors. The nesting order is important, but order is generally not important. In the sections that follow, the section header tells where the attribute belongs. For example, an attribute in caucho.com/http-server/host belongs in a host element which belongs in an http-server element which belongs in the caucho.com element.

The application configuration can be placed in WEB-INF/web.xml If web.xml exists, Resin will use it to configure the application.

Servlet configuration interacts with the application configuration. In particular, servlet-mapping tells Resin how to map urls to servlets.

Index
access-log
app-dir
browser-mapping
cache-mapping
chain-mapping
character-encoding
class-update-interval
classpath
context-param
directory-servlet
ejb-ref
env-entry
error-log
error-page
jdbc-store
jndi-link
jsp
login-config
mime-mapping
multipart-form
path-mapping
resource-ref
servlet
servlet-mapping
session-config
session-max
session-timeout
strict-mapping
taglib
tcp-store
temp-dir
url-pattern
welcome-file-list

access-log

Specifies the access logging. See the host access-log for more details.

By default, uses the host access-log.

app-dir

Specifies the directory of the application. If unspecified, the application will have the same path as the id. When the web-app is specified with a url-regexp, app-dir can use replacement variables ($2).

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

AttributeMeaningDefault
idThe url prefix selecting this application.n/a
url-regexpA regexp to select this application.n/a
app-dirThe root document directory for the application (can use regexp replacement variables.)Same as id or the regexp match

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<host id=''>
  <web-app id='/apache' app-dir='/usr/local/apache/htdocs'>

 ...

</host>

The following example sets the root application to the IIS root directory. The host and web-app will use the http-server app-dir as a default.

<caucho.com>
<http-server app-dir='c:\inetpub\wwwroot'>

 ...

</http-server>
</caucho.com>

In the following, each user gets her own independent application using ~user. (Note, since mod_caucho and IIS don't understand regexps, so you may need to manually configure the web server.)

<host id=''>

<web-app url-regexp='/~([^/]*)'
         app-dir='/home/$1/public_html'>

 ...

</web-app>

</host>

By default, uses the subdiretory under the host app-dir with the application's name.

browser-mapping

Browser-specific configuration. Used to deal with broken browsers.

AttributeMeaning
regexpRegular expression to match the User-Agent
force10If set, force HTTP/1.0

No default browser-mappings are defined.

classpath

Adds to the application-specific classpath. The classpath can also automatically compile java classes when the source attribute is specified.

Note: Each classpath directive must only contain a single class directory. In other words, you need two classpaths to specify "foo.jar:bar.jar".

AttributeDescriptionDefault
idSingle class directory or jarrequired
library-dirTo be used as a jar directory like WEB-INF/libfalse
sourceOptional java source directorysame as id
compileEnable automatic compilationtrue
encodingWhen compiling, what character encoding to usejavac default
argsWhen compiling, additional args to javacnone

For example, to automatically compile classes in the WEB-INF/classes directory

<classpath id='WEB-INF/classes'
           source='WEB-INF/classes'
	   compile='true'/>

To compile classes into the WEB-INF/classes directory with the source in a home work directory:

<classpath id='WEB-INF/classes'
           source='/home/ferg/ws/src'/>
<classpath id='/home/test/library/classes'/>

By default, WEB-INF/classes is compiled and WEB-INF/lib contains jars.

class-update-interval

Interval in seconds between checking for servlet updates. For development, this can be set to 0 or to a small number to pick up new servlet versions quickly. For deployment, class-update-interval can be large to avoid the overhead of checking for updates.

The default value is 2 seconds.

character-encoding

Specifies the default character encoding for form parameters.

<web-app id='/' character-encoding='shift_jis'>

  ...

</web-app>

The default value is ISO-8859-1.

cache-mapping

Specifies Expires times for cacheable pages. Uncacheable pages, e.g. pages with sessions, are not affected.

AttributeMeaning
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
expiresA time interval.
The time interval defaults to seconds, but will allow other periods:

SuffixMeaning
sseconds
mminutes
hhours
ddays

<web-app id='/'>

<cache-mapping url-pattern='/*'
              expires='10'/>

<cache-mapping url-pattern='*.gif'
              expires='15m'/>

</web-app>

There is no default value.

chain-mapping

Defines a Servlet filter to transform the output of another servlet based on mime-type. By default, the content type x-application/xsl executes com.caucho.jsp.XslFilter.

For example, a servlet could call setContentType("x-application/xsl") to format its XML results using XSL.

AttributeDescription
mime-typeThe mime-type to match
servlet-nameThe servlet name to execute
Filter XML by an XSL processor
<chain-mapping mime-type='x-application/xsl'
                servlet-name='com.caucho.jsp.XslFilter'/>

Note: Versions before Resin 1.2.2 use filter-mapping instead of chain-mapping. This has been changed to avoid conflicts with the Servlet 2.3 spec

By default, Resin maps the x-application/xsl to com.caucho.jsp.XslFilter.

context-param

Initializes application variables. context-param defines initial values for application.getInitParameter("foo"). The full servlet 2.2 syntax is supported and allows a simple shortcut

<web-app id='/'>

<context-param foo='bar'/>

<context-param>
  <param-name>baz</param-name>
  <param-value>value</param-value>
</context-param>

</web-app>

directory-servlet

Specifies the servlet to use to display directories. To disable directory listing, set this to 'none'.

<web-app id='/'>

  <directory-servlet>none</directory-servlet>

</web-app>

The default is com.caucho.server.http.DirectoryServlet.

env-entry

JNDI parameter configuration. env-entry binds JNDI variables, similar to either init-param or context param. env-entry is useful for configuring non-servlet-aware classes, like EJBs.

AttributeMeaning
env-entry-nameJNDI path attribute to store the variable
env-entry-typeJava type of the variable
env-entry-valueThe variable value.
Example resin.conf fragment
<env-entry>
  <env-entry-name>max-price</env-entry-name>
  <env-entry-type>java.lang.Double</env-entry-type>
  <env-entry-value>22.27</env-entry-type>
</env-entry>
Example test.jsp
<%@ page import="javax.naming.*" %>
<%
Context env = new InitialContext().lookup("java:comp/env");

Double dValue = (Double) env.lookup("max-price");
double price = dValue.doubleValue();
%>

ejb-ref

Instantiates a EJB client bean. Normally, EJB clients use jndi-link instead. There are EJB configuration examples for some vendors.

Attribute>Meaning
ejb-ref-nameJNDI path attribute to store the bean
ejb-ref-typeEJB class type
ejb-ref-factoryFactory for creating an EJB client bean (Resin 1.2)
init-paramParameter for the factory (Resin 1.2)

error-log

Specifies the file for error logging. See the host error-log for more details.

The default uses the containing host's error log.

error-page

A page to display if the current request fails. The web server plugins use a special case of error-page to handle connection failures.

AttributeDescription
locationThe error page to display
exceptionSelect the error page based on a Java exception
error-codeSelect the error page based on an HTTP status code
Catching File Not Found
<web-app id='/'>
    <error-page error-code='404'
                location='/file_not_found.jsp'/>
</web-app>
Catching Exceptions
<web-app id='/foo'>
      <error-page exception-type='java.lang.NullPointerException'
                  location='/nullpointer.jsp'/>
</web-app>

The following is a special case for the mod_caucho or isapi_srun plugin to redirect to another page if it can't connect to srun. Unlike the other two forms, this must be in http-server web-app as below. It can't be in a specific web-app.
Special can't connect to srun
<caucho.com>
<http-server>

<error-page exception-type='connection'
              location='/missing_file.html'/>
	      
</http-server>
</caucho.com>

By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages.

jdbc-store

Configure sessions to use a JDBC backing store The database must be specified using the resource-ref configuration. The database store will automatically create a table to store the sessions.

data-sourcedata source name for the table
table-namedatabase table for the session data
blob-typedatabase type for a blob
timestamp-typedatabase type for a blob
session-timeoutcleanup time
Example configuration
<session-config>
  <jdbc-store>
    <data-source>jdbc/sessions</data-source>
  </jdbc-store>
</session-config>
Example table created by session
CREATE TABLE session (
  id VARCHAR(64) NOT NULL,
  data BLOB,
  mod_time TIMESTAMP,
  PRIMARY KEY(id)
)

By default, Resin does not use JDBC persistent sessions.

jsp

JSP configuration

attributemeaningdefault
precompileuse precompiled JSP classes if available.true
sessionIf "false", disable sessions by default.true
static-encodingallow JSP to precompile character encoding.true
auto-compileif false, changes in .jsp will not force auto-compile.true

jndi-link

Links a foreign JNDI context to the Resin JNDI context. For example, you can use jndi-link to link in client EJBs from a foreign EJB container.

AttributeDescription.
jndi-nameJNDI path attribute to bind the link
property-filejndi.property to use to obtain the Context.
jndi-factoryClass name of an InitialContextFactory used to create the bean.
init-paramProperties to be used to get the initial context.
jndi-lookupJNDI path for the foreign context.
Linking a WebLogic EJB client bean
<jndi-link>
  <jndi-name>java:comp/env/ejb/traderHome</jndi-name>
  <jndi-factory>weblogic.jndi.WLInitialContextFactory</jndi-factory>
  <init-param java.naming.provider.url="t3://localhost:7001"/>
  <jndi-lookup>statelessSession.TraderHome</jndi-lookup>
</jndi-link>

By default, Resin does not add any special JNDI links.

login-config

Configures user authentication. See auth config for more details.

AttributeMeaning
auth-methodAuthentication method
form-login-configConfiguration for form login
authenticatorSelect authenticator class
security-constraintSelect the files to protect.

By default, Resin does not authenticate.

mime-mapping

Maps url patterns to mime-types.

AttributeMeaning
extensionurl extension
mime-typethe mime-type

<web-app id='/'>

<mime-mapping extension='.foo'
              mime-type='text/html'/>

</web-app>

Resin has a long list of default mime types in com.caucho.server.http.Application.

multipart-form

Enables multipart-mime for forms and file uploads.

For an uploaded file with a form name of foo, the parameter value contains the path name to a temporary file containing the uploaded file. foo.filename contains the uploaded filename, and foo.content-type contains the content-type of the uploaded file.

AttributeMeaningDefault
enableif set false, this disables multipart-form processing.true
upload-maxmaximum size of an upload request.no limit
If the upload is larger than the limit or if multipart-form processing is disabled, Resin will not parse the request.

By default, multipart-form is disabled.

servlet-mapping

Maps url patterns to servlets. servlet-mapping has two children, url-pattern and servlet-name. url-pattern selects the urls which should execute the servlet.

servlet-name can either specify a servlet class directly or it can specify a servlet alias defined by servlet.

The special servlet-name invoker is used to dispatch servlets by class name. For example, /servlets/test.HelloServlet.

attributemeaningdefault
url-patternA pattern matching the url: /foo/*, /foo, or *.foon/a
url-regexpA regular expression matching the urln/a
servlet-nameThe servlet name (can use replacement vars like $1)n/a
path-infoPath info rewriting string (can use replacement vars like $1)The standard path-info
servlet-classThe servlet's classuses servlet-name
init-paramInitialization parametersn/a
load-on-startupInitializes the servlet when the server starts.none
run-atTimes to execute the servlet automaticallynone
case-sensitiveIf true, the match is case-sensitivetrue on Unix and false on Windows

<caucho.com>
<web-app id='/'>

<servlet servlet-name='hello'
         servlet-class='test.HelloWorld'/>

<servlet-mapping url-pattern='/hello.html'
                 servlet-name='hello'/>

<servlet-mapping url-pattern='/servlet/*'
                 servlet-name='invoker'/>

<servlet-mapping url-pattern='*.xtp'
                 servlet-name='com.caucho.jsp.XtpServlet'/>

</web-app>

The plugins use servlet-mapping to decide which URLs to send to Resin. The following servlet-name value are special:

plugin_matchThe plugin will send the request to Resin, but Resin will ignore the entry. Use to get around regexp limitations. (Resin 1.2.2)
plugin_ignoreThe plugin will ignore the request. Use this to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)

servlet

Defines a servlet alias for later mapping. More details are in the servlet configuration section.

AttributeMeaning
servlet-nameThe servlet's name (alias)
servlet-classThe servlet's class (defaults to servlet-name)
init-paramInitialization parameters
load-on-startupInitializes the servlet when the server starts.
run-atTimes to execute the servlet automatically (Resin 1.1)
The following example defines a servlet alias 'hello'

<web-app id='/'>

<servlet-mapping url-pattern='/hello.html'
                 servlet-name='hello'/>

<servlet servlet-name='hello'
         servlet-class='test.HelloWorld'>
  <init-param title='Hello, World'/>
</servlet>

<servlet servlet-name='cron'
         servlet-class='test.DailyChores'>
  <run-at>3:00</run-at>
</servlet>

</web-app>

session-config

Contains session configuration parameters

AttributeMeaningDefault
session-timeoutThe session timeout in minutes30 minutes
session-maxMaximum active sessions4096
enable-cookiesEnable cookies for sessions (resin 1.1)true
enable-url-rewritingEnable URL rewriting for sessions (resin 1.1)true
cookie-versionVersion of the cookie spec (resin 1.2)1.0
cookie-domainDomain for session cookies (resin 1.2)none
file-storePersistent sessions using a file store (resin 1.2)none
jdbc-storePersistent sessions using a JDBC store (resin 1.2)none
tcp-storePersistent sessions using a distributed ring (resin 1.2)none
always-load-sessionReload data from the store on every request (resin 1.2)false
always-save-sessionSave session data to the store on every request (resin 1.2)false
save-on-shutdownOnly save session when the application shuts down. (resin 1.2.3)false

By default, both enable-cookies and enable-url-rewriting are true. To force url rewriting, you would create a configuration like:

<web-app id='/'>

  <session-config
   enable-cookies='false'
   enable-url-rewriting='true'/>

</web-app>

session-timeout

Sets the session timeout in minutes. Sessions idle for longer than session-timeout are purged.

session-timeout must be contained in a session-config tag.

<web-app id='/dir'>

  <session-config session-timeout='120'/>

</web-app>

Defaults to 30 minutes.

session-max

Sets the maximum number of active sessions. Sessions are stored in an LRU cache. When the cache fills, the oldest sessions are recovered.

session-max must be contained in a session-config tag.

<web-app id='/dir'>

  <session-config>
     <session-timeout id=120/>
     <session-max id=4096/>
  </session-config>

</web-app>

Defaults to 4096.

taglib

Configures a JSP 1.1 tag library. See the tlb configuration for details.

AttributeDescription
taglib-uriMatching uri for the tag library
taglib-locationLocation for the tab library definition file.

The location is relative to the class path. In the following example, MyTag.tlb should be in WEB-INF/classes/MyTag.tlb.

<taglib taglib-uri='/mytag/test'
        taglib-location='/MyTag.tlb'/>

The JSP file will use the tag library as follows:

<%@ taglib prefix='x' uri='/mytag/test' %>
<x:mytag/>

By default, looks up all WEB-INF/*.tld and META-INF/*.tld.

tcp-store

Configure sessions to use a TCP-ring backing store. All the <srun> servers are arranged in a ring based on their order in the resin.conf. The tcp-store will store the session based on that ring order.
Example Symmetrical configuration
<http-server>
  <http id='a' port='80'/>
  <srun id='a' host='host-a' port='6802'/>

  <http id='b' port='80'/>
  <srun id='b' host='host-b' port='6802'/>

  <host id=''>
  <web-app id=''>

  <session-config>
    <tcp-store/>
    <always-load-session/>
  </session-config>

  </web-app>
  </host>
</http-server>
The above example assumes the two hosts use an external load-balancer, like a router load-balancer. Any request can come to either host-a or host-b, requiring always-load-session.

See distributed sessions for more details.

Disabled by default.

temp-dir

Application temp directory This is the path used in javax.servlet.context.tempdir.

Defaults to WEB-INF/tmp.

url-pattern

Matches a set of URLs for servlet-mapping.

PatternDescription
/foo/bar.htmlMatches exactly the /foo/bar.html URL.
/foo/*Matches /foo and any children
*.fooMatches any URL with a .foo extension
/Replaces the default servlet.

/ defines a default handler and /* defines a prefix handler. /* will override extension handlers like *.foo. / will only be used if no other pattern matches.

No default. Either url-pattern or url-regexp is required.

resource-ref

Database pooling configuration. resource-ref puts the DataSource in a JNDI context and also in the ServletContext. Each web-app can configure its own database pool. Resin can also share a common pool by putting the resource-ref outside the http-server.

The driver can be in WEB-INF/lib or WEB-INF/classes, although it's a better idea to put it in the global classpath or resin1.2/lib.

AttributeMeaning
res-ref-nameJNDI path attribute to store the pool
res-typejavax.sql.DataSource for database pools
init-paraminitialization parameters (Resin 1.2)
bean-nameoptional bean class to be used as a resource (Resin 1.2)

init-param sets bean properties of the data source. You can look at the com.caucho.sql.DBPool JavaDoc for its interface. Unknown parameters are used to set the driver properties. So you can set any driver-specific property in the init-param.

DBPool Init Parameters
AttributeMeaningDefault
driver-nameJDBC driver classrequired
urlJDBC url for the databaserequired
userDatabase user""
passwordDatabase password""
max-connectionsMaximum number of allowed connections20
max-idle-timeMaximum time an idle connection is kept in the pool5 sec
ping-tableThe database table used to "ping", checking that the connection is still live.false
ping-on-reuseTest for live connections before allocating them from the pool.false
ping-on-freeTest for live connections before replacing them in the pool.false
ping-on-idlePeriodically test connectiong in the poolfalse
connection-wait-timeHow long to wait for an idle connection (Resin 1.2.3)5 seconds
enable-transactionConnections from this pool can participate in a transaction. Enabling transactions adds overhead, so non-transaction applications should not set this.false
any othercalls DBPool.setProperty() to set driver properties.none

Here's a sample minimal resin.conf fragment to bind a DBPool-based database to the JNDI path "java:comp/env/jdbc/test".
Sample resin.conf fragment
<resource-ref>
  <res-ref-name>jdbc/test</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <init-param driver-name="org.gjt.mm.mysql.Driver"/>
  <init-param url="jdbc:mysql://localhost:3306/test"/>
</resource-ref>

The following is a sample design pattern for getting new database connections. The try ... finally block is very important for making database connections reliable.
Sample test.jsp to use database connections
<%@ page import='javax.sql.*, javax.naming.*, java.sql.*' %>
<%
Context env = new InitialContext().lookup("java:comp/env");

DataSource source = (DataSource) env.lookup("jdbc/test");
Connection conn = source.getConnection();
try {
  ...
} finally {
  conn.close();
}
%>

path-mapping

Maps url patterns to real paths. If using a server like IIS, you may need to match the server's path aliases.

AttributeMeaning
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
real-pathThe prefix of the real path. When used with url-regexp, allows substitution variables like $1.

<web-app id='/'>

<path-mapping url-pattern='/resin/*'
              real-path='e:\resin'/>

<path-mapping url-regexp='/~([^/]*)'
              real-path='e:\home\$1'/>

</web-app>

No default.

strict-mapping

Forces servlet-mapping to follow strict Servlet 2.2, disallowing PATH_INFO

Defaults to false, allowing /foo/bar.jsp/foo.

welcome-file-list

Sets the files to use as index.jsp pages

<web-app id='/'>
  <welcome-file-list>index.jsp, home.xtp</welcome-file-list>
</web-app>

Defaults to index.xtp, index.jsp, index.html.


HTTP Config
Configuration
Servlet Config
Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.