|
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.
Specifies the access logging. See
the host access-log for more details.
By default, uses the host access-log.
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.
| Attribute |
Meaning |
Default
|
| id |
The url prefix selecting this application. |
n/a
|
| url-regexp |
A regexp to select this application. |
n/a
|
| app-dir |
The 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
| Resin 1.1 |
Browser-specific configuration. Used to deal with
broken browsers.
| Attribute |
Meaning
|
| regexp |
Regular expression to match the User-Agent
|
| force10 |
If set, force HTTP/1.0
|
No default browser-mappings are defined.
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 |
Default
|
| id |
Single class directory or jar |
required
|
| library-dir |
To be used as a jar directory like WEB-INF/lib |
false
|
| source |
Optional java source directory |
same as id
|
| compile |
Enable automatic compilation |
true
|
| encoding |
When compiling, what character encoding to use |
javac default
|
| args |
When compiling, additional args to javac |
none
|
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
| Resin 1.1 |
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
| Resin 1.1 |
Specifies the default character encoding for form parameters.
<web-app id='/' character-encoding='shift_jis'>
...
</web-app>
|
The default value is ISO-8859-1.
Specifies Expires times for cacheable pages.
Uncacheable pages, e.g. pages with sessions, are not affected.
| Attribute |
Meaning
|
| 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:
| Suffix |
Meaning
|
| s |
seconds
|
| m |
minutes
|
| h |
hours
|
| d |
days
|
<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
| Resin 1.2.2 |
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.
| Attribute |
Description
|
| mime-type |
The mime-type to match
|
| servlet-name |
The 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
| Servlet 2.2 |
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
| Servlet 2.2 |
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.
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.
| Attribute |
Meaning
|
| env-entry-name |
JNDI path attribute to store the variable
|
| env-entry-type |
Java type of the variable
|
| env-entry-value |
The 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(); %>
|
Instantiates a EJB client bean. Normally, EJB clients
use jndi-link instead. There are
EJB configuration examples for some vendors.
| Attribute> |
Meaning
|
| ejb-ref-name |
JNDI path attribute to store the bean
|
| ejb-ref-type |
EJB class type
|
| ejb-ref-factory |
Factory for creating an EJB client bean
(Resin 1.2)
|
| init-param |
Parameter for the factory (Resin 1.2)
|
Specifies the file for error logging. See
the host error-log for more details.
The default uses the containing host's error log.
A page to display if the current request fails. The web
server plugins use a special case
of error-page to handle connection failures.
| Attribute |
Description
|
| location |
The error page to display
|
| exception |
Select the error page based on a Java exception
|
| error-code |
Select 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.
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-source |
data source name for the table
|
| table-name |
database table for the session data
|
| blob-type |
database type for a blob
|
| timestamp-type |
database type for a blob
|
| session-timeout |
cleanup 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 configuration
| attribute |
meaning |
default
|
| precompile |
use precompiled JSP classes if available. |
true
|
| session |
If "false", disable sessions by default. |
true
|
| static-encoding |
allow JSP to precompile character encoding. |
true
|
| auto-compile |
if false, changes in .jsp will not
force auto-compile. |
true
|
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.
| Attribute |
Description.
|
| jndi-name |
JNDI path attribute to bind the link
|
| property-file |
jndi.property to use to obtain the Context.
|
| jndi-factory |
Class name of an InitialContextFactory used to
create the bean.
|
| init-param |
Properties to be used to get the initial
context.
|
| jndi-lookup |
JNDI 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.
Configures user authentication. See
auth config for more details.
| Attribute |
Meaning
|
| auth-method |
Authentication method
|
| form-login-config |
Configuration for form login
|
| authenticator |
Select authenticator class
|
| security-constraint |
Select the files to protect.
|
By default, Resin does not authenticate.
Maps url patterns to mime-types.
| Attribute |
Meaning
|
| extension |
url extension
|
| mime-type |
the 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.
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.
| Attribute |
Meaning |
Default
|
| enable |
if set false, this disables multipart-form processing. |
true
|
| upload-max |
maximum 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
| Servlet 2.2 |
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.
| attribute |
meaning |
default
|
| url-pattern |
A pattern matching the url:
/foo/*, /foo, or *.foo
|
n/a
|
| url-regexp |
A regular expression matching the url |
n/a
|
| servlet-name |
The servlet name (can use replacement vars
like $1) |
n/a
|
| path-info |
Path info rewriting string (can use replacement
vars like $1) |
The standard path-info
|
| servlet-class |
The servlet's class |
uses servlet-name
|
| init-param |
Initialization parameters |
n/a
|
| load-on-startup |
Initializes the servlet when the server starts. |
none
|
| run-at |
Times to execute the servlet automatically |
none
|
| case-sensitive |
If true, the match is case-sensitive |
true 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_match |
The plugin will send the request to Resin, but
Resin will ignore the entry. Use to get around regexp limitations. (Resin 1.2.2)
|
| plugin_ignore |
The plugin will ignore the request. Use this
to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)
|
Defines a servlet alias for later mapping. More details are in the
servlet configuration section.
| Attribute |
Meaning
|
| 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 (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
| Servlet 2.2 |
Contains session configuration parameters
| Attribute |
Meaning |
Default
|
| session-timeout |
The session timeout in minutes |
30 minutes
|
| session-max |
Maximum active sessions |
4096
|
| enable-cookies |
Enable cookies for sessions (resin 1.1) |
true
|
| enable-url-rewriting |
Enable URL rewriting for sessions (resin 1.1) |
true
|
| cookie-version |
Version of the cookie spec (resin 1.2) |
1.0
|
| cookie-domain |
Domain for session cookies (resin 1.2) |
none
|
| file-store |
Persistent sessions using a file store (resin 1.2) |
none
|
| jdbc-store |
Persistent sessions using a JDBC store (resin 1.2) |
none
|
| tcp-store |
Persistent sessions using a distributed ring (resin 1.2) |
none
|
| always-load-session |
Reload data from the store on every request (resin 1.2) |
false
|
| always-save-session |
Save session data to the store on every request (resin 1.2) |
false
|
| save-on-shutdown |
Only 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
| Servlet 2.2 |
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.
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.
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/>
|
By default, looks up all WEB-INF/*.tld and META-INF/*.tld.
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.
Application temp directory This is the path used in
javax.servlet.context.tempdir.
Defaults to WEB-INF/tmp.
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.
No default. Either url-pattern or url-regexp is required.
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.
| Attribute |
Meaning
|
| res-ref-name |
JNDI path attribute to store the pool
|
| res-type |
javax.sql.DataSource for database pools
|
| init-param |
initialization parameters (Resin 1.2)
|
| bean-name |
optional 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
| Attribute |
Meaning |
Default
|
| driver-name |
JDBC driver class |
required
|
| url |
JDBC url for the database |
required
|
| user |
Database user |
""
|
| password |
Database password |
""
|
| max-connections |
Maximum number of allowed connections |
20
|
| max-idle-time |
Maximum time an idle connection is kept in
the pool |
5 sec
|
| ping-table |
The database table used to "ping", checking that
the connection is still live. |
false
|
| ping-on-reuse |
Test for live connections before allocating
them from the pool. |
false
|
| ping-on-free |
Test for live connections before replacing
them in the pool. |
false
|
| ping-on-idle |
Periodically test connectiong in the pool |
false
|
| connection-wait-time |
How long to wait for an idle connection (Resin 1.2.3) |
5 seconds
|
| enable-transaction |
Connections from this pool can participate in a
transaction. Enabling transactions adds overhead, so non-transaction applications should not set this. |
false
|
| any other
|
calls 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(); } %>
|
Maps url patterns to real paths. If using a server like
IIS, you may need to match the server's path aliases.
| Attribute |
Meaning
|
| 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.
|
<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.
Forces servlet-mapping to follow strict Servlet 2.2, disallowing
PATH_INFO
Defaults to false, allowing /foo/bar.jsp/foo.
welcome-file-list
| Servlet 2.2 |
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.
Copyright © 1998-2001 Caucho Technology. All rights reserved.
| Copyright © 1998-2001 Caucho Technology. All rights reserved.
|
 |
|