resin configure

1 Command Line

2 Sample Configurations

3 Topics

4 General Configuration

5 Environment Configuration

6 Server Configuration

7 Port Configuration

8 Virtual Host Configuration

9 Application Configuration

10 Deployment

11 Security Configuration

12 Clustering and Load Balancing

13 Cache Configuration

 

1.Command Line

Option Description 

-classpath xxx  Adds to the system classpath, default is determined from environment variable CLASSPATH 

-conf conf/resin.conf  specifies the resin.conf file 

-Dfoo=bar  sets the JVM system property `foo' to the value `bar' 

-install  (windows) install Resin as a service with a default name (but doesn't automatically start) 

-install-as name  (windows) install Resin as a named service (but doesn't automatically start) 

-Jxxx  passes xxx to the JVM 

-J-verbosegc  turns on JVM garbage collection information (recommended) 

-java_home xxx  sets the JDK, default is determined from environment variable JAVA_HOME or a heuristic search. 

-jvm-log file  (unix) sets the file to put output that cannot be captured by stdout-log and stderr-log, relative to -server-root, default is log/jvm.log 

-no-auto-restart  disables the automatic restart of the JVM if it exits abnormally 

-nojit  disables the Just-In-Time compiler, useful for debugging with some JDK's 

-pid file  (unix) sets the pid file, default is based on the -server-id 

-pid-dir dir  (unix) sets the directory to store pid files in 

-remove  (windows) remove Resin as a service with a default name 

-remove-as  (windows) remove Resin as a named service 

-resin-home dir  sets the resin.home value, default is determined from RESIN_HOME environment variable or a heuristic search. 

restart  (unix) restarts Resin as a daemon using the pid in the file specfied with -pid  

-server id  sets the resin.server_id value and limits http and srun activation to those with a matching server-id 

-server-root dir  establishes the root directory for server files and sets the resin.root value 

start  (unix) starts Resin as a daemon saving the pid in the file specfied with -pid 

stop  (unix) stops Resin as a daemon using the pid in the file specfied with -pid 

-verbose  show the Java environment before starting Resin 

-Xxxx  passes the -Xxxx configuration to the JVM 

-Xdebug  enable HotSwap class reloading (recommended) 

[edit]Memory Options

Option Description 

-J-verbosegc  turns on JVM garbage collection information (recommended) 

-Xmx256m  set the maximum heap size (recommended) 

-XX:MaxPermSize=256m  the maximum size of the permanent space (recommended) 

-Xss  the stack size, default is 1m 

 

The default values for -Xmx and -XX:MaxPermSize are generally too low for a normal deployment.

 

 

2 Sample Configurations

1) minimal.conf

<> <> <> <> <> <> <> <> <document-directory>

minimal resin.conf

       xmlns:resin="">

 

 

  

   

   

     

   

 

command line and -server-root

unix> bin/httpd.sh -server-root /var/www -conf conf/resin.conf

The argument specifies the main directory for the Resin instance. In this example, the document directory is in _/var/www/docs_.

As an alternative, either the <> or the <> can specify the actual <>, e.g. . Using the command line adds some flexibility, but also makes the resin.conf more difficult to read as a standalone file.

description

<>

The <> directive is the top-level directive for the resin.conf.

xmlns and xmlns:resin

The xmlns and xmlns:resin directives define the XML namespaces for the resin.conf. These namespaces are important for the configuration file validation.

<>

The <> configures a Resin server. Each <> listens to TCP ports (usually HTTP) and defines a number of [virtual hosts].

Although it is possible to have multiple <> items, most sites will only use a single <>.

<>

The <> directive tells Resin to listen to a HTTP port and interface.

<>

The <> imports a secondary XML file into the current configuration. In this case, the reads in the standard <[server]> configuration from [app-default.xml].

is a critical import file which defines the JSP servlet, the file servlet, and defines WEB-INF/classes, WEB-INF/lib, WEB-INF/ and WEB-INF/.

Without the import of , most of the expected behavior will not occur.

<>

The <> directive defines a . The <> directive is required, otherwise Resin will simply return messages.

The <> of a <> specifies the virtual host's directory. If the path is relative, the root-directory will be relative to the <> root-directory.

(If the <> root-directory is unspecified, it defaults to .)

<>

The <> directive defines a .

 

2) development.conf

       xmlns:resin="">

    2s

          WEB-INF/work/sessions

 

 

3) Sample resin.conf

       xmlns:core="">

    1h

                  format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'

                  rollover-period="1W"/>

        jdbc:postgresql://localhost/test

        potter

 

 

4) fine.conf

       xmlns:resin="">

 

Topics

1)      Logging

Access logging

An access log receives output describing each request received by the server. It is commonly used in conjunction with analysis tools to determine statistics and patterns of use for a website.

Examples

            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'

            rollover-period="1W"/>

stdout-log and stderr-log

The stdout-log and stderr-log directives capture and redirect the output of and .

Examples

configuration to capture and output to log files.

       xmlns:resin="">

 

              rollover-period='1W'/>

 

              rollover-period='1W'/>

   ...

log

Java programs (including Resin) can use the logging facilities included in the JDK. Log messages have a name and and a level.

Logging can be used to enable and to enable application specific logging that utilizes the JDK logging facilities.

Examples

resin.conf configuration to capture finer logging and display it on the console, useful during development:

       xmlns:resin="">

  ...

 

  ...

resin.conf configuration to capture finer request and response related logging from Resin, and all logging from the com.hogwarts application under development:

       xmlns:resin="">

 

 

   

   

   

 

   

 

   ...

 

Archiving

All log directives support archiving, when the log reaches a certain size or age a rollover occurs and the existing log is saved away while a new log is started.

path-format and archive-format are two mutually exclusive methods for archiving logs. Rollover determines the frequency at which the archive files are created.

path-format

path-format specifies the name of a file. The name contains escape sequences that are replaced with the current date and time. When the rollover occurs, a new file is started with the appropriate date and time. Thus path-format results in archive files that are named with the date and time of the first entry in the log.

...

  

               rollover-period="1D"/>

   ...

...

archive-format and path

Log messages are written to the file specified by . When a rollover occurs the contents of the file are copied to the archive-path. The archive-path contains escape sequences that are replaced with the current date and time. Thus archive-format results in log files that are named with the date and time of the last entry in the log.

archive-format can use a *.gz or *.zip extension to indicate that the archived log should be compressed.

            archive-path="/var/www/log/access.log.%Y%m%d.gz"

            rollover-period="1D"/>

Rollover

The fequency of the rollover is is specified with or .

rollover-period is a time based specification of a in days (15D), weeks (2W), months (1M), or hours (1h). When the specified time period has elapsed the rollover occurs.

rollover-size is a size based specification of a in bytes (50000), kb (128kb), or megabytes (10mb). When the log reaches the specified size the rollover occurs.

Disabling rollover

To completely disable rollovers, set the rollover-size to such a high number that it will never occur:

 

 

 

General Configuration

1)EL Configuration Variables

Globally Available Variables

Variable	Meaning
__FILE__	The current configuration file

Globally Available Functions

Function	Description
class_exists	True if the specified class exists in the environment
jndi	Looks up a resource in the JNDI environment
jndi_lookup	Synonym for jndi

environment Variables

Variable	Description
java	Information about the JDK version (3.0.17)
resin	The Resin variable object (see com.caucho.server.resin.ResinServer$Var)
resinHome	The Resin binary and library home
serverRoot	The root of the deployment/application data (defaults to to resinHome)

The java object has the following methods

Method	Description
isJava5()	True if the JDK supports JDK 1.5 or later (3.0.17)

The resin object has the following methods

Method	Description
id	returns the value of -server on the command line (3.0.15)
home	returns [-resin-home]
root	returns the deployment root directory, [-server-root] (3.0.15)
rootDir	return the deployment root directory (same as resin.root)
isProfessional()	returns true for a valid Resin professional installation

environment Variables

Variable	Description
server	information about the server environment

The server variable has a number of fields/methods available (defined in com.caucho.server.resin.ServerController$Var)

Attribute	Description
id	The value of -server id from the command line
root	Returns the server's data directory, [-server-root] (3.0.15)
rootDir	The server's root directory (same as server.root)

environment variables

Variable	Description
host	information about the host environment

 

Method	Description
root	the host's root directory (3.0.15)
rootDir	the host's root directory (same as host.root)
hostName	the host's canonical name
URL	the host's URL
regexp	any regular expression values for a host-regexp

environment variables

Variable	Description
webapp	information about the web-app environment

 

Method	Description
id	the web-app's unique name
name	the name of the war file (minus the .war)
root	the root of the web-app's directory
rootDir	the root of the web-app's directory (same as webapp.root)
contextPath	the web-app's context path
regexp	any regexp values from a url-regexp

 

2)Configuration EL Library

Resin 3.0.14 has added the capability of adding functions to the resin.conf EL expressions.

The builtin functions are:

1.     class_exists - test if the class is loadable

2.     jndi_lookup - perform a jndi lookup of the name

3.     jndi - shorthand for jndi_lookup

The standard configuration library is com.caucho.config.lib.ResinConfigLibrary.

Libraries are configured using the standard META-INF/services convention.

First, create a Java class with static methods you'd like to create as a library.

Then create a META-INF/services/com.caucho.config.ConfigLibrary file:

com.caucho.config.ConfigLibrary file

com.foo.MyLibrary

For example, you could create an add method:

package com.foo;

 

public class MyLibrary {

  public static int add(int a, int b)

  {

    return a + b;

  }

}

Then, in your resin.conf you could use EL expressions like "${add(3, 17)}"

 

3)Control directives

The directives in the namespace provide general configuration abilities like conditional configuration.

In general, we recommend avoiding the use of resin:if and resin:choose when possible, in order to keep configuration files manageable.

directive	meaning
<>	configures a block conditionally
	imports a file into the current directive
	output a log message during configuration
	sets a variable or jndi-value
	selects one of a group of choices.

resin:import imports a configuration file into the current tag. The configuration file will match the current context, the a resin:import file in a will be an XML file with a <web-app> tag.

tag	meaning
	a set of files to import
path	the file to import
optional	if true, the target is optional

The web.xml and resin-web.xml files are loaded with a resin:import tag in the conf/app-default.xml file.

[]

app-default.xml

...

  ...

...

 

 

4)resin:import

resin:import imports a configuration file into the current tag. The configuration file will match the current context, the a resin:import file in a will be an XML file with a <web-app> tag.

tag	meaning
	a set of files to import
path	the file to import
optional	if true, the target is optional

The web.xml and resin-web.xml files are loaded with a resin:import tag in the conf/app-default.xml file.

app-default.xml

...

  ...

...

 

5)Custom Configuration

Overview

Resin provides a configuration API to populate application beans from an XML file. Resin's configuration machinery supports Inversion of Control and allows the use of EL expressions.

Using Resin to parse XML

Resin's configuration API is the easiest method to parse XML.

Create Java classes mirroring the XML file.

Call Resin's configuration with an instance of the classes and the XML file.

Calling the Configuration

import com.caucho.config.*;

...

Config config = new Config();

MovieListing movies = new MovieList();

InputStream is = ...;

config.configure(bean, is);

Sample XML Parsing

Sample XML File

To model the XML file, you'll use a Movie class and a MovieListener class:

Movie.java

public class Movie {

  private String _director;

  private String _title;

  public void setDirector(String director)

  {

    _director = director;

  }

  public void setTitle(String title)

  {

    _title = title;

  }

}

The movie listing encapsulates a list of movies

MovieListing.java

public class MovieListing {

  private ArrayList _movies = new ArrayList();

  public void addMovie(Movie movie)

  {

    _movies.add(movie);

  }

}

 

Environment Configuration

1)Environment

Environment

directive	meaning	default
<authenticator>	configures an authenticator
<>	configures a user bean (see Inversion of Control)
	marks the environment as case-insensitive for URLs and filenames	false
	UTF-8
<>	configures the class loaders for the environment
<>	configures an EJB server or Amber
	configures a constant
<database>	configures a database
<dependency>	adds a named file as a dependency to the environment
<dependency-check-interval>	how often the environment should be checked for changes
	configures the java compiler for internal compilation
	links an external reference to the local JNDI or renames a JNDI name
<log>	configures the java.util.logging log
	configures a javax.naming.Reference object
<>	configures a block conditionally
<>	imports a file into the current directive
resin:message	output a log message during configuration
<>	sets a variable or jndi-value
<>	selects one of a group of choices.
	configures a user resource or bean (see Inversion of Control)
	default configuration for a .rar resource
	configures a directory for .rar expansion
	redirects System.err
	redirects System.out
	sets a value of System.getProperty
	configures a temporary directory
	WEB-INF/work

Retrieved from ""

 

 

 

2) Database Configuration

Connection Configuration

The JDBC connections can be initialized with specified values of the transaction-isolation, catalog, and read-only values. The directive configures these:

resin.conf

    ...

    read-committed

Transaction (XA) Configuration

The directive in the <database> configuration specifies how the connections should participate in distributed transactions.

If true, connections automatically participate in any , i.e. a .begin() will enlist the connection into the new transaction and commit() will commit the transactions.

The default value is true.

Non-transactional data sources

In some cases, it is convenient to have a transactional (xa) data source and a non-transactional data source to the same database. For example, a connection that only selects data from read-only tables does not need to participate in a transaction. In that case, it is more efficient to mark the read-only connection as non-transactional by setting false

Retrieved from ""

 

 

Server Configuration

1)

The directive is the resin.conf top-level configuration directive.

directive	description
Environment	Any Environment directive may be used in
security-provider	configures the security provider for JSSE
security-manager	enables the Java security manager
<server>	configures a server
shutdown-wait-max	maximum time Resin will wait for an orderly shutdown before forcing a close
<>	configures the thread pool
<>	configures the transaction manager

resin.conf

       xmlns:resin="">

  ...

    ...

directive	description
	the minimum number of idle threads required in the pool
	the maximum number of threads in the pool

 

2)

Server

The <server> directive occurs in the <resin> top-level directive. It allows any Environment configuration.

Multiple <server> directives are allowed as long as they have different id values.

directive	meaning	default
Environment	Any Environment directive is allowed in the
access-log	server-wide access log configuration
alternate-session-url-prefix	none
bind-ports-after-start	false
cache	configures the (Resin Professional only)
cluster	configures the server's cluster
	error page to use when IIS cannot connect to Resin (3.0.19)
ear-default	default configuration for .ear files
enable-select-manager	enables the poll/select management of keepalive connections	false
environment-system-properties	environment-specific System.getProperties	true
error-page	server-wide error page configuration
http	configures a http port
host	configures a virtual host
host-default	configures default for all virtual hosts
host-deploy	configures a deployment directory for virtual host archives
id	""
invocation-cache-size	size of the invocation cache	16k
invocation-cache-max-url-length	maximum length of a cacheable URL	1024
ignore-client-disconnect	if true, absorb
keepalive-max	the maximum number of keepalive sockets
keepalive-timeout	maximum time a keepalive thread will wait for a new request
<persistent-store>	configures the persistent store
ping	configures relability checking (Resin Professional only)
port	configures a custom port listener
Dispatches requests based on the URL
root-directory	the root directory for the server	$SERVER_ROOT
server-header	configures the value of the HTTP "Server:" header	Resin/3.0.x
session-cookie	configures the servlet session cookie name	JSESSIONID
ssl-session-cookie	configures the cookie to use for SSL connections	JSESSIONID
session-url-prefix	configures the URL rewriting prefix	;jsessionid=
url-character-encoding	configures the character encoding of URLs	UTF-8
web-app-default	configures server-wide defaults for all web-apps

 

3)Security Configuration

<>

As part of the HTTP response, Resin sends its name and version number in a server header, e.g. Server: Resin/3.0.14. Some sites prefer to change that header to a different value to hide the software version that's running the site.

To enable this, in the block use

resin.conf

...

  ...

  Foo/1.0

  ...

 

4)Log Configuration

Access logging

An access log receives output describing each request received by the server. It is commonly used in conjunction with analysis tools to determine statistics and patterns of use for a website.

Examples

            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'

            rollover-period="1W"/>

stdout-log and stderr-log

The stdout-log and stderr-log directives capture and redirect the output of System.out and System.err.

Examples

resin.conf configuration to capture System.out and System.err output to log files.

       xmlns:resin="">

 

              rollover-period='1W'/>

 

              rollover-period='1W'/>

  ...

log

Java programs (including Resin) can use the logging facilities included in the JDK. Log messages have a name and and a level.

Logging can be used to enable Resin logging names and to enable application specific logging that utilizes the JDK logging facilities.

Examples

resin.conf configuration to capture finer logging and display it on the console, useful during development:

       xmlns:resin="">

  ...

 

  ...

resin.conf configuration to capture finer request and response related logging from Resin, and all logging from the com.hogwarts application under development:

       xmlns:resin="">

 

 

   

   

   

 

   

 

  ...

Archiving

All log directives support archiving, when the log reaches a certain size or age a rollover occurs and the existing log is saved away while a new log is started.

path-format and archive-format are two mutually exclusive methods for archiving logs. Rollover determines the frequency at which the archive files are created.

path-format

path-format specifies the name of a file. The name contains date format escape sequences that are replaced with the current date and time. When the rollover occurs, a new file is started with the appropriate date and time. Thus path-format results in archive files that are named with the date and time of the first entry in the log.

...

  

               rollover-period="1D"/>

   ...

...

archive-format and path

Log messages are written to the file specified by path. When a rollover occurs the contents of the file are copied to the archive-path. The archive-path contains date format escape sequences that are replaced with the current date and time. Thus archive-format results in log files that are named with the date and time of the last entry in the log.

archive-format can use a *.gz or *.zip extension to indicate that the archived log should be compressed.

            archive-path="/var/www/log/access.log.%Y%m%d.gz"

            rollover-period="1D"/>

Rollover

The fequency of the rollover is is specified with rollover-period or rollover-size.

rollover-period is a time based specification of a period in days (15D), weeks (2W), months (1M), or hours (1h). When the specified time period has elapsed the rollover occurs.

rollover-size is a size based specification of a size in bytes (50000), kb (128kb), or megabytes (10mb). When the log reaches the specified size the rollover occurs.

Disabling rollover

To completely disable rollovers, set the rollover-size to such a high number that it will never occur:

 

Retrieved from ""

 

 

Port Configuration

1)

directive	description	default
connection-max	the maximum number of connections allowed	1024
host	the IP interface to listen to, "*" to listen to all interfaces	"*"
jsse-ssl	jsse configuration
keepalive-max	maximum number of connections allowed	512
max-spare-listen	maximum number of threads listening for a new connection	10
min-spare-listen	minimum number of threads listening for a new connection	5
openssl	openssl configuration
port	the TCP port to listen to	required
read-timeout	how long to listen to an idle socket for a read	30s
server-id	matches the -server command line option
socket-listen-backlog	sets the operating system's listen() value
tcp-no-delay	sets the TCP NO_DELAY flag
virtual-host	specifies a virtual host name to be used for IP-based virtual hosting
write-timeout	how long to try to write to a socket before failing	30s

 

2)

Port

It is possible to configure Resin to listen to custom protocols using the directive. is like <http> or <srun> in that it listens to a port and accepts connections, but it allows you to choose a custom protocol.

In fact, <http> and <srun> are specializations of port:

Configuring a HTTP port

       xmlns:resin="">

...

 

   

 

  ...

Configuring a Srun port outside of a cluster

       xmlns:resin="">

...

 

   

 

  ...

 

 

3)

A srun is a backend port listing to requests from a load balancer.

configuration directives

directive	description	default
server-id	matches the -server command line argument	""
connection-max	maximum number of concurrent connections allowed	4096
host	the host interface to listen to or "*" for all interfaces	"*"
index	optional index for sticky sessions (not recommended)	the ordered value in the srun list
keepalive-max	maximum number of keepalive connections for this port	1024
<openssl>	configures the port to require SSL using OpenSSL
<jsse-ssl>	configures the port to require SSL using JSSE
port	configures the port to listen to
protocol	optional protocol to use	hmux
read-timeout	how long to wait for a read on an idle socket	, 30s
socket-listen-backlog	queue size for the operating system listen() value	100
tcp-no-delay	sets the TCP no-delay value	true
timeout	default value for read-timeout and write-timeout	30s
backup	If true, the server is generally used as a backup	false
write-timeout	how long to wait for a write on an idle socket	, 30s

 

Virtual Host Configuration

1)

The directive can use any Environment configuration item. The host is allowed in the <server> directive. The host configuration can occur in the <host> directive or in a <host-default> or <host-deploy> directive.

directive	meaning	default
Environment	Any Environment configuration directive is allowed in the host
access-log	Host-specific access logging
document-directory	A default document-directory for child web-apps	optional
ear-default	Default configuration for .ear files
ear-deploy	Configures an .ear deployment directory
error-page	Custom error pages for unhandled error codes
host-alias	an alias virtual host name for this host
host-alias-regexp	a regular expression of host name aliases for the host
host-name	the canonical host name
id	configures the unique host identifier
regexp	creates virtual hosts based on a regular expression
rewrite-dispatch	rewrites URLs and can redirect or return error codes
	specifies the virtual hosts's root directory	recommended
redeploy-mode	configures the hot-deployment redeploy mode
startup-mode	configures the hot-deployment startup mode
web-app-deploy	configures a web-app deployment directory (webapps)
web-app-default	configures host-wide defaults for all web-applications
web-app	directly configures child web-apps

 

       xmlns:resin="">

...

  ...

 

        root-directory="/var/www/foo.com">

    foo.com

    web.foo.com

   

       

 

  ...

 

 

2)

Host-default

Contains default <host> configuration for all virtual hosts in a <server> (or in a <host-deploy>.)

host-default can be useful for configuring all virtual hosts with a common directory structure or access logging. For example, to configure all virtual hosts to use a directory and have a separate root web-app in docs, you could use:

resin.conf

...

  ...

..

 

 

3)

Host-deploy

The directive configures a host expansion directory like the web-app's directory.

Essentially, it's an automatic directory for directives with archive-path attributes.

For example, in the default resin.conf, if you drop a foo.jar in /hosts, it will expand to hosts/foo and be browseable at .

It's also possible to create a without a .jar file by creating a directory in the hosts.

  ...

 

   

 

  ...

attribute	description	default
path	The location for both expansion directories and archives	none
archive-directory	The location for archive (.jar) files	path
expand-directory	The directory where archives are expanded	path
host-name	An EL expression for auto-generated host names	none
expand-cleanup-fileset	List of files to delete on redeploy	delete entire archive
require-file	additional files which will force a reload	none
startup-mode	starting mode of deployed hosts	"automatic"
redeploy-mode	mode for checking an redeploying hosts	"automatic"
host-default	default configuration for all hosts	none

 

Application Configuration

1)

Web-app

The allows all the Environment configuration as well as the following:

directive	meaning	default
access-log	Configures an specific to the web-app
active-wait-time	how long to wait for the web-app to start before returning a 503
allow-servlet-el	allow EL expressions in init-param directives.
<archive-path>	location of the web-app's .war file
	Configures the expires time for cacheable pages
cookie-http-only	sets the HttpOnly attribute of the session cookie
context-param	configures the ServletContext.getContextParam() values
context-path	overrides the default context-path for the web-app
dispatch-wraps-filters	if true, RequestDispatcher simply wraps the requsts for filters	false
display-name	informational: debug name for the web-app
distributable	informational: marks the web-app as clusterable	true
ear-deploy	configures a directory for .ear expansion
ejb-local-ref	informational: describes local EJBs used in the web-app
ejb-ref	informational: describes remote EJBs used in the web-app
error-page	configures user-specified error pages
filter	configures a filter
filter-mapping	maps a filter to a url
idle-time	for lazy-load web-apps, specifies how long the web-app can remain idle before closing
	configures the jsp (obsolete)
	configures the jsp
listener	configures a listener for web-app events
login-config	configures the servlet-standard login mechanism
message-destination	informational: describes a JMS destination in the web-app
mime-mapping	configures Content-Type values based on filename extensions
multipart-form	configures file uploading
path-mapping	configures getRealPath aliasing
	web-app configuration which should apply before the web-app-default
resource-env-ref	informational: describes JNDI resources used in the web-app
	how long Resin should wait to redeploy a failed web-app (3.0.19)	60s
<redeploy-mode>	how Resin will restart a changed web-app
<rewrite-dispatch>	rewrites URLs and returns error pages and forwarding
<rewrite-real-path>	rewrites getRealPath aliasing
secure	marks the web-app as requiring a secure request
security-constraint	configures the servlet security constraint
security-role	informational: describes security roles used in the web-app
servlet	configures a servlet
servlet-mapping	maps a url to a servlet
servlet-regexp	maps a servlet using regular expressions
	configures the session
shutdown-wait-max	how long to wait for all threads to exit on shutdown before forcing an exit
<startup-mode>	how the web-app will be started on Resin startup
strict-mapping	forces exact URL matches
taglib	configures additional JSP taglibs used in the JSP
web-app	configures a child web-app
web-app-deploy	configures a child webapps deployment directory
welcome-file-list	configures the files to be used as index.html files

 

2)

Web-app-default

The directive is a default configuration for all [web-apps|web-app] in a [host]. It can contain all the children of a <[web-app]> directive. It can be particularly useful with the <[web-app-deploy]> directive in combination with <[resin:import|resin import]>.

The directive can appear in the <server>, the <host>, and the <web-app-deploy> directives.

The best example of is in the file in $RESIN_HOME/conf/app-default.xml in the standard distribution. That configures always-available servlets like the JSP servlet and the File servlet, as well as configuring WEB-INF/classes, WEB-INF/lib, and web.xml and resin-web.xml.

app-default.xml

    ...

 

 

3)

Web-app-deploy

The directive configures the directory, i.e. a location where you can drop .war files and have them expanded to web-apps.

Essentially, it's an automatic directory for directives with archive-path attributes.

For example, in the default resin.conf, if you drop a foo.war in /webapps, it will expand to webapps/foo and be browseable at .

It's also possible to create a Web Application without a .war files by creating a directory in the webapps without

...

...

attribute	description	default
path	The location for both expansion directories and archives	none
archive-directory	The location for archive (.war) files	path
expand-directory	The directory where archives are expanded	path
expand-prefix	Prefix to generate the expanded directory	""
expand-suffix	Suffix to generate the expanded directory	""
url-prefix	Prefix for any URL access	none
expand-cleanup-fileset	List of files to delete on redeploy	delete entire archive
require-file	additional files which will force a reload	none
startup-mode	starting mode of deployed web-apps	automatic
redeploy-mode	mode for checking an redeploying web-apps	automatic
web-app-default	default configuration for all web-apps	none
web-app	overriding configuration for any deployed webapps	none

 

4)

Rewrite-dispatch

The directive rewrites and dispatches rules similar to the Apache mod_rewrite module. It can appear in the <host> or the <web-app> directives.

Overview

The directive tries each sub-directive in order for a match. The first matching directive redirects the request.

may occur in a <host> or in a <web-app>.

Starting with Resin 3.0.19, may also occur in the <server> block. The regexp in that case will be the entire URL, not just the path portion.

Escaping

Since the rewrite rules are written in Resin's XML configuration files, XML escaping rules apply. In particular a & character must be escaped with &

302 Redirecting a URL

To redirect a URL with a HTTP 302 redirect use:

 

301 Permanently Move a URL

To redirect a URL with a HTTP 301 moved-permanently use:

 

(requires Resin 3.0.18)

Forwarding a URL

To internally forward a URL to a target using the Servlet forward() call use:

 

403 Forbidden

To send a HTTP 403 forbidden message for a URL, use:

 

404 Not Found

To send a HTTP 404 Not Found message for a URL, use:

 

410 Gone

To send a HTTP 410 Gone message for a URL, use:

 

 

 

5)resin-web.xml

The resin-web.xml file, located in WEB-INF, is the place to configure Resin-specific web-app configuration. All the usual web.xml directives are supported as well as simplifying the web.xml syntax to make the configuration more readable.

Since most applications will only be deploying to a single web server, they will typically just create a resin-web.xml as the configuration file in WEB-INF. Applications which expect to deploy in multiple web servers will generally create a web.xml with servlet-standard configuration and a separate resin-web.xml for additional configuration for databases and other resources.

For validation, the resin-web.xml should declare the Resin validation namespace: . This will let Resin catch XML configuration errors early and give information about the errors.

resin-web.xml

    ...

    ...

Resin reads the web.xml and resin-web.xml in order, so configuration in the resin-web.xml can override the configuration in the web.xml.

Since Resin 3.0 tries to avoid defaults, the import of web.xml and resin-web.xml is defined in the conf/app-default.xml file as follows:

app-default.xml

        xmlns:resin="">

  ...