config-webapp.xtp

RESIN 3.2 最新源码

&lt;document-directory&gt; is used to match web-apps.</p>

<example title="overriding web.xml">
&lt;web-app-deploy path="webapps"&gt;
  &lt;web-app context-path="/wiki"
              document-directory="wiki"&gt;
    &lt;context-param database="jdbc/wiki"&gt;
  &lt;/web-app&gt;
&lt;/web-app-deploy&gt;
</example>

</s2>

</s1>

<s1 title="Servlet 2.4">

<p>Resin implements the Servlet 2.4 specification.</p>

<s2 title="description" version="Servlet" type="defun">
</s2>

<s2 title="display-name" version="Servlet" type="defun">
</s2>

<s2 title="distributable" version="Servlet" type="defun">
</s2>

<s2 title="context-param" version="Servlet 2.2" type="defun">
<parents>web-app</parents>

<p>Initializes application (ServletContext) variables.  <var>context-param</var>
defines initial values for <code>application.getInitParameter("foo")</code>.  See also
<a href="javadoc|javax.servlet.ServletContext|getInitParameter(String)"/>.</p>

<example title="context-param">
&lt;web-app id='/'&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;baz&lt;/param-name&gt;
    &lt;param-value&gt;value&lt;/param-value&gt;
  &lt;/context-param&gt;

  &lt;!-- shortcut --&gt;
  &lt;context-param foo='bar'/&gt;

&lt;/web-app&gt;
</example>
</s2>

<s2 title="filter" version="Servlet 2.3" type="defun">
<p>Defines a filter alias for later mapping.</p>

<deftable-childtags>
<tr><td>filter-name</td><td>The filter's name (alias)
</td></tr><tr><td>filter-class</td><td>The filter's class (defaults to filter-name), which extends <a href="javadoc|javax.servlet.Filter|"/>
</td></tr><tr><td>init-param</td><td>Initialization parameters, see <a href="javadoc|javax.servlet.FilterConfig">FilterConfig.getInitParameter(String)</a>.
</td></tr></deftable-childtags>

<p>The following example defines a filter alias 'image'</p>
<example>
&lt;web-app id='/'&gt;

  &lt;filter&gt;
    &lt;filter-name&gt;image&lt;/filter-name&gt;
    &lt;filter-class&gt;test.MyImage&lt;/filter-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;title&lt;/param-name&gt;
      &lt;param-value&gt;Hello, World&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/filter&gt;

  &lt;filter-mapping&gt;
    &lt;filter-name&gt;image&lt;/filter-name&gt;
    &lt;url-pattern&gt;/images/*&lt;/url-pattern&gt;
  &lt;/filter-mapping&gt;

&lt;/web-app&gt;
</example>

<p>The full Servlet 2.3 syntax for <var>init-param</var> is supported as
well as a simple shortcut.</p>

<example>
&lt;web-app id='/'&gt;

&lt;filter filter-name='test.HelloWorld'&gt;
  &lt;init-param foo='bar'/&gt;

  &lt;init-param&gt;
    &lt;param-name&gt;baz&lt;/param-name&gt;
    &lt;param-value&gt;value&lt;/param-value&gt;
  &lt;/init-param&gt;
&lt;/servlet&gt;

&lt;/web-app&gt;
</example>
</s2>

<s2 title="filter-mapping" version="Servlet 2.3" type="defun">
<p>Maps url patterns to filters.  <var>filter-mapping</var> has two
children, <var>url-pattern</var> and <var>filter-name</var>.
<var>url-pattern</var> selects the urls which should execute the filter.
</p>

<p><code>filter-name</code> can either specify a servlet class directly or it
can specify a servlet alias defined by <code>filter</code>.
</p>

<deftable-childtags title="Servlet 2.4 definition for filter-mapping">
<tr><td>filter-name</td><td>The filter name
</td></tr><tr><td>url-pattern</td><td>A pattern matching the url: <var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var>
</td></tr><tr><td>dispatcher</td><td>
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to filter-mapping">
<tr><td>url-regexp</td><td>A regular expression matching the url
</td></tr><tr><td>filter-name</td><td>The filter name can use replacement vars
from url-regexp like <var>$1</var>.  It can also specify a
class name directly like <var>test.HelloWorld</var></td><td>n/a
</td></tr></deftable-childtags>

<example>
&lt;web-app&gt;

  &lt;filter&gt;
    &lt;filter-name&gt;test-filter&lt;/filter-name&gt;
    &lt;filter-class&gt;test.MyFilter&lt;/filter-class&gt;
  &lt;/filter&gt;

  &lt;filter-mapping&gt;
    &lt;filter-name&gt;test-filter&lt;/filter-name&gt;
    &lt;url-pattern&gt;/hello/*&lt;/url-pattern&gt;
  &lt;/filter-mapping&gt;

  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;test.HelloWorld&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/hello&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</example>
</s2>

<s2 title="listener" version="Servlet" type="defun">
</s2>

<s2 title="servlet" version="Servlet 2.2" type="defun">
<p>Defines a servlet alias for later mapping using <a config-tag="servlet-mapping"/>.</p>

<deftable-childtags>
<tr><td>servlet-name</td><td>The servlet's name (alias)
</td></tr><tr><td>servlet-class</td><td>The servlet's class (In Resin, defaults to servlet-name)
</td></tr><tr><td>init-param</td><td>Initialization parameters
</td></tr><tr><td>load-on-startup</td><td>Initializes the servlet when the server starts.
</td></tr><tr><td>run-at</td><td>Times to execute the servlet automatically,
A Resin extension.
</td></tr></deftable-childtags>

<example title="using the &lt;servlet&gt; tag">
&lt;web-app id='/'&gt;

  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;test.HelloWorld&lt;/servlet-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;title&lt;/param-name&gt;
      &lt;param-value&gt;Hello, World&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/servlet&gt;

  &lt;!-- using Resin shortcut syntax --&gt;
  &lt;servlet servlet-name='cron'
           servlet-class='test.DailyChores'&gt;
    &lt;init-param title='Daily Chores'/&gt;
    &lt;load-on-startup/&gt;
    &lt;run-at&gt;3:00&lt;/run-at&gt;
  &lt;/servlet&gt;

  &lt;!-- mapping a url to use the servlet --&gt;
  &lt;servlet-mapping url-pattern='/hello.html'
                   servlet-name='hello'/&gt;

&lt;/web-app&gt;
</example>


<p>Several <var>servlet</var> configurations might configure the same
servlet class with different <var>init-param</var> values.  Each will
have a separate <var>servlet-name</var>.</p>
      
<example title="multiple servlets using the same class">
&lt;web-app&gt;
  &lt;servlet servlet-name='foo-a'&gt;
    &lt;servlet-class&gt;test.FooServlet&lt;/servlet-class&gt;
    &lt;init-param name='foo-a sample'/&gt;
  &lt;/servlet&gt;

  &lt;servlet servlet-name='foo-b'&gt;
    &lt;servlet-class&gt;test.FooServlet&lt;/servlet-class&gt;
    &lt;init-param name='foo-b sample'/&gt;
  &lt;/servlet&gt;
&lt;/web-app&gt;
</example>

<p><var>load-on-startup</var> 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.</p>
      
<p>There are a number of named servlets that are usually
available to a Resin application, as defined in
<var>$RESIN_HOME/conf/app-default.xml</var>.</p>

<example title="servlet-mapping's in $RESIN_HOME/conf/app-default.xml">
  &lt;servlet servlet-name="directory"
           servlet-class="com.caucho.servlets.DirectoryServlet"/&gt;

  &lt;servlet servlet-name="file"
           servlet-class="com.caucho.servlets.FileServlet"/&gt;

  &lt;servlet servlet-name="jsp"
           servlet-class="com.caucho.jsp.JspServlet"/&gt;

  &lt;servlet servlet-name="xtp"
           servlet-class="com.caucho.jsp.XtpServlet"/&gt;

&lt;servlet servlet-name="j_security_check"
         servlet-class="com.caucho.server.security.FormLoginServlet"/&gt;
</example>
</s2>

<s2 title="servlet-mapping" version="Servlet 2.2" type="defun">
<p>Maps url patterns to servlets.  <var>servlet-mapping</var> has two
children, <var>url-pattern</var> and <var>servlet-name</var>.
<var>url-pattern</var> selects the urls which should execute the servlet.</p>

<deftable-childtags title="Servlet 2.4 definition for servlet-mapping">
<tr><td>servlet-name</td><td>The servlet name</td><td>n/a
</td></tr><tr><td>url-pattern</td><td>A pattern matching the url:
<var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var></td><td>n/a
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to servlet-mapping">
<tr><td>url-regexp</td><td>A regular expression matching the url</td><td>n/a
</td></tr><tr><td>servlet-name</td><td>The servlet name can use replacement vars
from url-regexp like <var>$1</var>.  It can also specify a
class name directly like <var>test.HelloWorld</var></td><td>n/a
</td></tr></deftable-childtags>

<example title="servlet-mapping">
&lt;web-app id='/'&gt;

  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;test.HelloWorld&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;url-pattern&gt;/hello.html&lt;/servlet-class&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-class&gt;
  &lt;/servlet-mapping&gt;

  &lt;!-- resin shortcut syntax --&gt;
  &lt;servlet-mapping url-pattern='*.xtp'
                   servlet-name='com.caucho.jsp.XtpServlet'/&gt;

&lt;/web-app&gt;
</example>
<p>In Resin, the special <code>servlet-name</code> <var>`invoker'</var> is used to dispatch
servlets by class name.
</p>

<warn>Enabling the <var>invoker</var> 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.</warn>

<example title="servlet invoker">
&lt;web-app id='/'&gt;

  &lt;!-- 
    used with urls like 
    http://localhost:8080/servlets/test.HelloServlet 
  --&gt;
  &lt;servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/&gt;

&lt;/web-app&gt;
</example>

<p>There are a number of mappings to servlets that are usually
available to a Resin application, as defined in
<var>$RESIN_HOME/conf/app-default.xml</var>.</p>

<example title="servlet-mapping's in $RESIN_HOME/conf/app-default.xml">
&lt;servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/&gt;
&lt;servlet-mapping url-pattern="*.xtp" servlet-name="xtp"/&gt;

&lt;servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/&gt;
&lt;servlet-mapping url-pattern="/" servlet-name="file"/&gt;
</example>

<p>The plugins use servlet-mapping to decide which URLs to send to Resin.
The following servlet-name values are used by the plugins:</p>

<deftable title="servlet-name values used by plugins">
<tr><td>plugin_match</td><td>The plugin will send the request to Resin, but
Resin will ignore the entry.  Use to get around regexp limitations. (Resin 1.2.2)
</td></tr><tr><td>plugin_ignore</td><td>The plugin will ignore the request.  Use this
to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)
</td></tr></deftable>
</s2>

<s2 title="servlet-regexp" version="Resin 3.0" type="defun">
<p>Maps URL by regular expressions to custom servlets.</p>

<example>
&lt;servlet-regexp url-regexp="/([^.]*).do"
                servlet-class="qa.\${regexp[1]}Servlet"&gt;
  &lt;init a="b"/&gt;
&lt;/servlet-regexp&gt;
</example>

</s2>

<s2 title="session-config" version="Servlet 2.2" type="defun">
<p>Session configuration parameters.</p>

<deftable-childtags title="Servlet 2.4 definition for session-timeout">
<tr><td>session-timeout</td><td>The session timeout in minutes, 0 means never timeout.</td><td>30 minutes
</td></tr></deftable-childtags>

<p>Resin add's a number of <var>session-config</var> tags.</p>

<deftable-childtags title="Resin extensions to session-config">
<tr><td>session-max</td><td>Maximum active sessions</td><td>4096
</td></tr><tr><td>enable-cookies</td><td>Enable cookies for sessions. (resin 1.1)</td><td>true
</td></tr><tr><td>enable-url-rewriting</td><td>Enable URL rewriting for sessions. (resin 1.1)</td><td>true
</td></tr><tr><td>cookie-version</td><td>Version of the cookie spec for sessions. (resin 1.2)</td><td>1.0
</td></tr><tr><td>cookie-domain</td><td>Domain for session cookies. (resin 1.2)</td><td>none
</td></tr><tr><td>cookie-max-age</td><td>Max age for persistent session cookies. (resin 2.0)</td><td>none
</td></tr><tr><td>cookie-length</td><td>Maximum length of the cookie. (resin 2.1.1)</td><td>Integer.MAX_VALUE
</td></tr><tr><td>file-store</td><td>Persistent sessions using a file store. (resin 1.2)</td><td>none
</td></tr><tr><td>use-persistent-store</td><td>Uses the current <a href="resin.xtp#persistent-store">persistent-store</a> to save sessions. (resin 3.0.8)</td><td>none
</td></tr><tr><td>always-load-session</td><td>Reload data from the store on every request. (resin 1.2)</td><td>false
</td></tr><tr><td>always-save-session</td><td>Save session data to the store on every request. (resin 1.2)</td><td>false
</td></tr><tr><td>save-only-on-shutdown</td><td>Only save session when the application shuts down. (resin 1.2.3)</td><td>false
</td></tr><tr><td>reuse-session-id</td><td>Reuse the session id even if the session has timed out. (resin 2.0.4)</td><td>true
</td></tr><tr><td>ignore-serialization-errors</td><td>When persisting a session, ignore any values which don't implement java.io.Serializable</td><td>false
</td></tr><tr><td>invalidate-after-listener</td><td>. (resin 3.0)</td><td>
</td></tr></deftable-childtags>