caucho
Resin 1.1
FAQ
Reference
JavaDoc
Demo
Java Tutorial

Getting Started
Configuration
Servlet
JSP
XTP/XSL
JavaScript
JS Library

Resin Config
HTTP Config
App Config
Servlet Config
Login Config
Taglib Config
Virtual Hosts
Caching
 Web Application Configuration

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.

web-app
app-dir Specifies the directory of the application.
servlet-mapping Maps url patterns to servlets.
mime-mapping Maps url patterns to mime-types.
path-mapping Maps url patterns to real paths.
filter-mapping Defines a Servlet filter to transform the output of another servlet based on mime-type.
cache-mapping Specifies Expires times for cacheable pages.
url-pattern Matches a set of URLs for servlet-mapping.
servlet Defines a servlet alias for later mapping.
context-param Initializes application variables.
session-config Contains session configuration parameters
session-timeout Sets the session timeout in minutes.
session-max Sets the maximum number of active sessions.
class-update-interval Interval in seconds between checking for servlet updates.
character-encoding Specifies the default character encoding for form parameters.
directory-servlet Specifies the servlet to use to display directories.
classpath Adds to the application-specific classpath.
welcome-file-list Sets the files to use as index.jsp pages
taglib Configures a JSP 1.1 tag library.
temp-dir Application temp directory
jsp JSP configuration

web-app

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.

id The url prefix selecting this application.
url-regexp A regexp to select this application.
app-dir The root document directory for the application (can use regexp replacement variables.)

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

<caucho.com>
<http-server>
  <web-app id='/apache' app-dir='/usr/local/apache/htdocs'>

 ...

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

The following example sets the root application to the IIS root directory.

<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.)

<caucho.com>
<http-server>

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

 ...

</web-app>

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

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.

url-pattern A pattern matching the url: /foo/*, /foo, or *.foo
url-regexp A regular expression matching the url
servlet-name The servlet name (can use replacement vars like $1)
path-info Path info rewriting string (can use replacement vars like $1)

<caucho.com>
<http-server>

<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'/>

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

mime-mapping

Maps url patterns to mime-types.

<caucho.com>
<http-server>

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

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

path-mapping

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

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

<caucho.com>
<http-server>

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

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

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

filter-mapping

Resin 1.1

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.

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

cache-mapping

Resin 1.1

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

url-pattern A pattern matching the url: /foo/*, /foo, or *.foo
url-regexp A regular expression matching the url
expires A time interval.
The time interval defaults to seconds, but will allow other periods:

s seconds
m minutes
h hours
d days

<caucho.com>
<http-server>

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

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

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

url-pattern

Matches a set of URLs for servlet-mapping.

Pattern Description
/foo/bar.html Matches exactly the /foo/bar.html URL.
/foo/* Matches /foo and any children
*.foo Matches 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.

servlet

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

servlet-name The servlet's name (alias)
servlet-class The servlet's class (defaults to servlet-name)
init-param Initialization parameters
load-on-startup Initializes the servlet when the server starts.
run-at Times to execute the servlet automatically
The following example defines a servlet alias 'hello'

<caucho.com>
<http-server>

<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>

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

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

<caucho.com>
<http-server>

<context-param foo='bar'/>

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

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

session-config

Contains session configuration parameters

session-timeout The session timeout in minutes
session-max Maximum active sessions
enable-cookies Enable cookies for sessions
enable-url-rewriting Enable URL rewriting for sessions

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

<http-server>

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

</http-server>

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.

<caucho.com>
<http-server>

<web-app id='/dir'>

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

</web-app>

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

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.

<caucho.com>
<http-server>

<web-app id='/dir'>

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

</web-app>

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

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.

character-encoding

Specifies the default character encoding for form parameters. If unspecified, the application will use the system default encoding.

<caucho.com>
<http-server character-encoding='shift_jis'>

  ...

</http-server>

directory-servlet

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

classpath

Resin 1.1

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".

Attribute Description
id Single class directory (no jars)
source Optional java source directory
compile Enable automatic compilation (true by default)

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'/>

welcome-file-list

Sets the files to use as index.jsp pages

<http-server>
  <welcome-file-list>index.jsp, home.xtp</welcome-file-list>
</http-server>

taglib

Resin 1.1

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

Attribute Description
taglib-uri Matching uri for the tag library
taglib-location Location 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/>

temp-dir

Resin 1.1

Application temp directory This is the path used in javax.servlet.context.tempdir. It defaults to WEB-INF/tmp.

jsp

Resin 1.1

JSP configuration

precompile use precompiled JSP classes if available
session enable/disable sessions by default
static-encoding allow JSP to precompile character encoding

HTTP Config   Servlet Config
Copyright © 1998-2000 Caucho Technology. All rights reserved.
Last modified: Thu, 30 Mar 2000 14:43:23 -0800 (PST)