|
|
web-app-default, web-app
Specifies Expires times for cacheable pages.
cache-mapping is intended to provide Expires times for pages that
have Last-Modified or ETags specified, but do not wish to hard-code the
Expires timeout in the servlet. For example, Resin's FileServlet relies
on cache-mapping to set the expires times for static pages.
| 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
|
- cache-mapping requires an enabled <cache>. If the cache is disabled,
cache-mapping will be ignored.
- cache-mapping does not automatically make a page cacheable. Only
cacheable pages are affected by cache-mapping, i.e. pages with an ETag or Last-Modified.
<web-app id='/'>
<cache-mapping url-pattern='/*'
expires='10'/>
<cache-mapping url-pattern='*.gif'
expires='15m'/>
</web-app>
web-app-default, web-app
Specifies configuration files for the web-app.
The use of files like WEB-INF/web.xml and WEB-INF/resin-web.xml
are configured using <config-file>. You can add application-specific
configuration files using the <config-file> tag.
Configuration files will be read and applied in the order they
are specified.
...
<config-file>WEB-INF/web.xml</config-file>
<config-file>WEB-INF/resin-web.xml</config-file>
...
host, web-app
Specifies ear expansion.
ear-deploy can be used in web-apps to define a subdirectory
for ear expansion.
| path | The path to the deploy directory | required
|
| expand-path | directory where ears should be expanded | value of path
|
web-app-default, web-app
Configures JSP behavior.
| auto-compile | Automatically compile changed JSP files | true
|
| el-ignored | Ignore EL expressions in JSP text | false
|
| fast-jstl | Optimize JSTL JSP compilation | true
|
| ignore-el-exception | Ignore exceptions generated in EL expressions | true
|
| is-xml | Default JSP pages to use XML syntax | false
|
| precompile | Try to load precompiled JSP pages | true
|
| recompile-on-error | Recompile the JSP file when an Error occurs in loading | false
|
| require-source | Return 404 when JSP source is deleted | false
|
| dependency-check-interval | How often to check the jsp for changes, -1 disables | inherited
|
| session | Creates sessions for each JSP page | true
|
| velocity-enabled | Enable Velocity statements | false
|
The class that corresponds to <jsp> is
web-app-default, web-app
Enables multipart-mime for forms and file uploads. multipart-mime
is disabled by default.
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.
| upload-max | maximum size of an upload request (in kb). | no limit
|
If the upload is larger than the limit or if multipart-form processing
is disabled, Resin will not parse the request and will set an error message
in the "caucho.multipart.form.error" request attribute.
The "caucho.multipart.form.error.size" will contain the attempted upload size.
Requests can set the maximum by setting the request attribute
"caucho.multipart.form.upload-max" with an Integer or Long value.
By default, multipart-form is disabled.
web-app-default, web-app
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.
|
<web-app id='/'>
<path-mapping url-pattern='/resin/*'
real-path='e:\resin'/>
<path-mapping url-regexp='/~([^/]*)'
real-path='e:\home$1'/>
</web-app>
The maximum time Resin will wait for requests to finish before closing the web-app.
false, allowing /foo/bar.jsp/foo.
Forces servlet-mapping to follow strict Servlet 2.2, disallowing
PATH_INFO. Value is true or false.
<web-app>
<strict-mapping>true</strict-mapping>
</web-app>
server, host-default, host
Establishes the defaults for a .
When initializing a web-app, all the tags in
the web-app-defaults sections configure the web-app. In other words,
the web-app-default value is essentially a macro that is cut-and-pasted
before the web-app configuration.
web-app-default is used for defining server-wide behavior, like *.jsp
handling, and for host-wide behavior.
<host>
<web-app-default>
<servlet servlet-name='test'
servlet-class='test.MyServlet'/>
<servlet-mapping url-pattern='*.text' servlet-class='test'/>
</web-app-default>
</host>
host-default, host, WEB-INF/web.xml, WEB-INF/resin-web.xml
web-app configures a web application.
| id | The url prefix selecting this application. | n/a
|
| url-regexp | A regexp to select this application. | n/a
|
| document-directory | The document directory for
the application, corresponding to a url of /id/. A relative path is relative to the of the containing . Can use regexp replacement variables. | A relative path constricted with the id or the regexp match
|
| startup-mode | `automatic', `lazy', or `manual', see Startup and Redeploy Mode | automatic
|
| redeploy-mode | `automatic' or `manual', see Startup and Redeploy Mode | automatic
|
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.
The following example creates a web-app for /apache
using the Apache htdocs directory to serve pages.
<host id=''>
<web-app id='/apache' document-directory='/usr/local/apache/htdocs'>
...
</host>
The following example sets the root web-app to the IIS
root directory.
<web-app id='/' document-directory='C:/inetpub/wwwroot'>
When the web-app is specified with a url-regexp,
document-directory can use replacement variables ($2).
In the following, each user gets his or her own independent
application using ~user.
<host id=''>
<web-app url-regexp='/~([^/]*)'
document-directory='/home/$1/public_html'>
...
</web-app>
</host>
host, web-app
Specifies war expansion.
web-app-deploy can be used in web-apps to define a subdirectory
for war expansion. The tutorials in the documentation
use web-app-deploy to allow servlet/tutorial/helloworld to be an
independent war file.
| path | The path to the webapps directory | required
|
| url-prefix | url-prefix added to all expanded webapps | ""
|
| expand-path | directory where wars should be expanded | value of path
|
| lazy-init | true if web-apps should only be initialized when first used | false
|
| web-app-default | defaults to be applied to expaned web-apps |
|
| web-app | overriding configuration for specific web-apps |
|
The web-app-deploy can override configuration for an expanded war with
a matching <web-app> inside the <web-app-deploy>. The
<document-directory> is used to match web-apps.
<web-app-deploy path="webapps">
<web-app context-path="/wiki"
document-directory="wiki">
<context-param database="jdbc/wiki">
</web-app>
</web-app-deploy>
Resin implements the Servlet 2.4 specification.
web-app
Initializes application (ServletContext) variables. context-param
defines initial values for application.getInitParameter("foo"). See also
.
<web-app id='/'>
<context-param>
<param-name>baz</param-name>
<param-value>value</param-value>
</context-param>
<!-- shortcut -->
<context-param foo='bar'/>
</web-app>
Defines a filter alias for later mapping.
| filter-name | The filter's name (alias)
|
| filter-class | The filter's class (defaults to filter-name), which extends
|
| init-param | Initialization parameters, see
|
The following example defines a filter alias 'image'
<web-app id='/'>
<filter>
<filter-name>image</filter-name>
<filter-class>test.MyImage</filter-class>
<init-param>
<param-name>title</param-name>
<param-value>Hello, World</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>image</filter-name>
<url-pattern>/images/*</url-pattern>
</filter-mapping>
</web-app>
The full Servlet 2.3 syntax for init-param is supported as
well as a simple shortcut.
<web-app id='/'>
<filter filter-name='test.HelloWorld'>
<init-param foo='bar'/>
<init-param>
<param-name>baz</param-name>
<param-value>value</param-value>
</init-param>
</servlet>
</web-app>
Maps url patterns to filters. filter-mapping has two
children, url-pattern and filter-name.
url-pattern selects the urls which should execute the filter.
filter-name can either specify a servlet class directly or it
can specify a servlet alias defined by filter.
| filter-name | The filter name
|
| url-pattern | A pattern matching the url: /foo/*, /foo, or *.foo
|
| dispatcher |
|
| url-regexp | A regular expression matching the url
|
| filter-name | The filter name can use replacement vars
from url-regexp like $1. It can also specify a
class name directly like test.HelloWorld | n/a
|
<web-app>
<filter>
<filter-name>test-filter</filter-name>
<filter-class>test.MyFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>test-filter</filter-name>
<url-pattern>/hello/*</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>hello</servlet-name>
<servlet-class>test.HelloWorld</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>hello</servlet-name>
<url-pattern>/hello</url-pattern>
</servlet-mapping>
</web-app>
Defines a servlet alias for later mapping using .
| servlet-name | The servlet's name (alias)
|
| servlet-class | The servlet's class (In Resin, 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,
A Resin extension.
|
<web-app id='/'>
<servlet>
<servlet-name>hello</servlet-name>
<servlet-class>test.HelloWorld</servlet-class>
<init-param>
<param-name>title</param-name>
<param-value>Hello, World</param-value>
</init-param>
</servlet>
<!-- using Resin shortcut syntax -->
<servlet servlet-name='cron'
servlet-class='test.DailyChores'>
<init-param title='Daily Chores'/>
<load-on-startup/>
<run-at>3:00</run-at>
</servlet>
<!-- mapping a url to use the servlet -->
<servlet-mapping url-pattern='/hello.html'
servlet-name='hello'/>
</web-app>
Several servlet configurations might configure the same
servlet class with different init-param values. Each will
have a separate servlet-name.
<web-app>
<servlet servlet-name='foo-a'>
<servlet-class>test.FooServlet</servlet-class>
<init-param name='foo-a sample'/>
</servlet>
<servlet servlet-name='foo-b'>
<servlet-class>test.FooServlet</servlet-class>
<init-param name='foo-b sample'/>
</servlet>
</web-app>
load-on-startup can specify an (optional) integer
value. If the value is 0 or greater, it indicates an order for
servlets to be loaded, servlets with higher numbers get loaded
after servlets with lower numbers.
There are a number of named servlets that are usually
available to a Resin application, as defined in
$RESIN_HOME/conf/app-default.xml.
<servlet servlet-name="directory"
servlet-class="com.caucho.servlets.DirectoryServlet"/>
<servlet servlet-name="file"
servlet-class="com.caucho.servlets.FileServlet"/>
<servlet servlet-name="jsp"
servlet-class="com.caucho.jsp.JspServlet"/>
<servlet servlet-name="xtp"
servlet-class="com.caucho.jsp.XtpServlet"/>
<servlet servlet-name="j_security_check"
servlet-class="com.caucho.server.security.FormLoginServlet"/>
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 | The servlet name | n/a
|
| 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
from url-regexp like $1. It can also specify a
class name directly like test.HelloWorld | n/a
|
<web-app id='/'>
<servlet>
<servlet-name>hello</servlet-name>
<servlet-class>test.HelloWorld</servlet-class>
</servlet>
<servlet-mapping>
<url-pattern>/hello.html</servlet-class>
<servlet-name>hello</servlet-class>
</servlet-mapping>
<!-- resin shortcut syntax -->
<servlet-mapping url-pattern='*.xtp'
servlet-name='com.caucho.jsp.XtpServlet'/>
</web-app>
In Resin, the special servlet-name `invoker' is used to dispatch
servlets by class name.
Enabling the invoker servlet can
create a security hole in your application. Any servlet in the
classpath, perhaps even one in a .jar that you are unaware of,
could be invoked.
<web-app id='/'>
<!-- used with url like http://localhost:8080/servlets/test.HelloServlet -->
<servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>
</web-app>
There are a number of mappings to servlets that are usually
available to a Resin application, as defined in
$RESIN_HOME/conf/app-default.xml.
<servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/>
<servlet-mapping url-pattern="*.xtp" servlet-name="xtp"/>
<servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>
<servlet-mapping url-pattern="/" servlet-name="file"/>
The plugins use servlet-mapping to decide which URLs to send to Resin.
The following servlet-name values are used by the plugins:
| 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)
|
Maps URL by regular expressions to custom servlets.
<servlet-regexp url-regexp="/([^.]*).do"
servlet-class="qa.${regexp[1]}Servlet">
<init a="b"/>
</servlet-regexp>
Session configuration parameters.
| session-timeout | The session timeout in minutes, 0 means never timeout. | 30 minutes
|
Resin add's a number of session-config tags.
| 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 for sessions. (resin 1.2) | 1.0
|
| cookie-domain | Domain for session cookies. (resin 1.2) | none
|
| cookie-max-age | Max age for persistent session cookies. (resin 2.0) | none
|
| cookie-length | Maximum length of the cookie. (resin 2.1.1) | Integer.MAX_VALUE
|
| file-store | Persistent sessions using a file store. (resin 1.2) | none
|
| use-persistent-store | Uses the current persistent-store to save sessions. (resin 3.0.8) | 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-only-on-shutdown | Only save session when the application shuts down. (resin 1.2.3) | false
|
| reuse-session-id | Reuse the session id even if the session has timed out. (resin 2.0.4) | true
|
| ignore-serialization-errors | When persisting a session, ignore any values which don't implement java.io.Serializable | false
|
| invalidate-after-listener | . (resin 3.0) |
|
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>
The session-timeout and session-max are usually
used together to control the number of
sessions. Sessions are stored in an LRU cache. When the number
of sessions in the cache fills up past session-max, the
oldest sessions are recovered. In addition, sessions idle for
longer than session-timeout are purged.
<web-app id='/dir'>
<session-config>
<!-- 2 hour timeout -->
<session-timeout>120</session-timeout>
<session-max>4096</session-max>
</session-config>
</web-app>
cookie-length is used to limit the maximum length for
the session's generated cookie for special situations like WAP devices.
Reducing this value reduces the randomness in the cookie and increases the
chance of session collisions.
reuse-session-id defaults to true so that Resin can share the session
id amongst different web-apps.
The class that corresponds to <session-config> is
web-app-default, web-app
Maps url patterns to mime-types.
| extension | url extension
|
| mime-type | the mime-type
|
<web-app id='/'>
<mime-mapping>
<extension>.foo</extension>
<mime-type>text/html</mime-type>
</mime-mapping>
<!-- resin shortcut syntax -->
<mime-mapping extension='.bar'
mime-type='text/html'/>
</web-app>
Resin has a long list of default mime types in $RESIN_HOME/conf/app-default.xml
web-app-default, web-app
in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.
Sets the files to use as when no filename is present in
url. According to the spec, each file is in a <welcome-file>
element.
<web-app id='/'>
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.xtp</welcome-file>
<welcome-file>home.xtp</welcome-file>
</welcome-file-list>
</web-app>
Resin also provides a shortcut where you can just list the files:
<web-app id='/'>
<welcome-file-list>index.jsp, index.xtp, home.xtp</welcome-file-list>
</web-app>
web-app-default, web-app
| error-code | Select the error page based on an HTTP status code
|
| exception-type | Select the error page based on a Java exception
|
| location | The error page to display
|
By default, Resin returns a 500 Servlet Error and a stack trace for
exceptions and a simple 404 File Not Found for error pages. Applications can
customize the response generated for errors.
<web-app>
<error-page>
<error-code>404</error-code>
<location>/file_not_found.jsp</location>
</error-page>
</web-app>
<web-app id='/foo'>
<error-page exception-type='java.lang.NullPointerException'
location='/nullpointer.jsp'/>
</web-app>
The error page can use request attributes to obtain information about the
request that caused the error:
<%@ page session="false" isErrorPage="true" %>
<html>
<head><title>404 Not Found</title></head>
<body>
<h1>404 Not Found</h1>
The url <code>${requestScope["javax.servlet.error.request_uri"]}</code>
was not found.
</body>
</html>
| Attribute | Type
|
|---|
| javax.servlet.error.status_code | java.lang.Integer
|
| javax.servlet.error.message | java.lang.String
|
| javax.servlet.error.request_uri | java.lang.String
|
| javax.servlet.error.servlet_name | java.lang.String
|
| javax.servlet.error.exception | java.lang.Throwable
|
| javax.servlet.error.exception_type | java.lang.Class
|
web-app-default, web-app
Specifies protected areas of the web site. Sites using
authentication as an optional personalization feature will typically
not use any security constraints.
Security constraints can also be custom classes.
<security-constraint>
<web-resource-collection>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint role-name='user'>
</security-constraint>
security-constraint
security-constraint
Specifies a collection of areas of the web site.
| web-resource-name | a name for a web resource collection
|
| description |
|
| url-pattern | url patterns describing the resource
|
| http-method | HTTP methods to be restricted.
|
| method |
|
security-constraint
Requires that authenticated users fill the specified role.
In Resin's JdbcAuthenticator, normal users are in the "user" role.
Think of a role as a group of users.
| role-name | Roles which are allowed to access the resource.
|
security-constraint
Restricts access to secure transports, such as SSL
| transport-guarantee | Required transport properties. NONE,
INTEGRAL, and CONFIDENTIAL are allowed values.
|
security-constraint
Defines a custom constraint.
| resin:type | A class that extends
|
| init | initialization parameters, set in the object using Bean-style setters and getters
|
web-app-default, web-app
no authentication
| auth-method | Authentication method, either BASIC for HTTP Basic Authentication, FORM for form based authentication, or DIGEST for HTTP Digest Authentication.
|
| realm-name | The realm name to use in HTTP authentication
|
| form-login-config | Configuration for form login, see
|
| type | Defines a custom class which extends com.caucho.server.security.AbstractLogin
|
| init | Initialization for the custom login class
|
HTTP Authentication is defined in the RFC HTTP Authentication: Basic and
Digest.
HTTP digest authentication is discussed in Digest Passwords.
login-config
Configures authentication using forms. The login form has
specific parameters that the servlet engine's login form processing
understands. If the login succeeds, the user will see the original
page. If it fails, she will see the error page.
| form-login-page | The page to be used to prompt the user login | none
|
| form-error-page | The error page for unsuccessful login | none
|
| internal-forward | Use an internal redirect on success instead of a sendRedirect | false
|
| form-uri-priority | If true, the form's j_uri will override a stored URI | false
|
The form itself must have the action j_security_check. It
must also have the parameters j_username and j_password.
Optionally, it can also have j_uri and
j_use_cookie_auth. j_uri gives the next page to display
when login succeeds. j_use_cookie_auth allows Resin to send a
persistent cookie to the user to make following login easier.
j_use_cookie_auth gives control to the user whether to generate
a persistent cookie. It lets you implement the "remember me" button. By
default, the authentication only lasts for a single session.
| j_security_check | The form's mandatory action
|
| j_username | The user name
|
| j_password | The password
|
| j_uri | Optional Resin extension for the successful display page.
|
| j_use_cookie_auth | Optional Resin extension to allow cookie login.
|
The following is an example of a servlet-standard login page:
<form action='j_security_check' method='POST'>
<table>
<tr><td>User:<td><input name='j_username'>
<tr><td>Password:<td><input name='j_password'>
<tr><td colspan=2>hint: the password is 'quidditch'
<tr><td><input type=submit>
</table>
</form>
web-app-default, web-app
web-app-default, web-app
Copyright (c) 1998-2009 Caucho Technology, Inc. All rights reserved.
caucho® ,
resin® and
quercus®
are registered trademarks of Caucho Technology, Inc.
|
