webapp-tags.xtp

RESIN 3.2 最新源码

element servlet-regexp {
  init?
  & servlet-class?
  & servlet-name?
  & url-regexp
}
</def>

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

</defun>

<defun title="&lt;session-config>" version="Servlet 2.2">

<p>&lt;session-config> configures Resin's session handling, including the
cookies Resin sends, the maximum sessions, and session persistence and clustering.</p>

<p>See also: <a href="resin-clustering.xtp">Resin clustering</a> for more
information about distributed sessions and persistence.</p>

<deftable title="&lt;session-config> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>always-load-session</td>
  <td>Reload data from the store on every request</td>
  <td>false</td>
</tr>
<tr>
  <td>always-save-session</td>
  <td>Save session data to the store on every request</td>
  <td>false</td>
</tr>
<tr>
  <td>enable-cookies</td>
  <td>Enable cookies for sessions</td>
  <td>true</td>
</tr>
<tr>
  <td>enable-url-rewriting</td>
  <td>Enable URL rewriting for sessions</td>
  <td>true</td>
</tr>
<tr>
  <td>cookie-version</td>
  <td>Version of the cookie spec for sessions</td>
  <td>1.0</td>
</tr>
<tr>
  <td>cookie-domain</td>
  <td>Domain for session cookies</td>
  <td>none</td>
</tr>
<tr> 
  <td>cookie-max-age</td>
  <td>Max age for persistent session cookies</td>
  <td>none</td>
</tr>
<tr>
  <td>cookie-length</td>
  <td>Maximum length of the cookie</td>
  <td></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>If true, invalidate the sessions after the session listeners have
been called</td>
  <td></td>
</tr>
<tr>
  <td>reuse-session-id</td>
  <td>Reuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)</td>
  <td>true</td>
</tr>
<tr>
  <td>session-max</td>
  <td>Maximum active sessions</td>
  <td>4096</td>
</tr>
<tr>
  <td>session-timeout</td>
  <td>The session timeout in minutes, 0 means never timeout.</td>
  <td>30 minutes</td>
</tr>
<tr>
  <td>serialization-type</td>
  <td>Use one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)</td>
  <td>java</td>
</tr>
<tr>
  <td>save-mode</td>
  <td>When to save sessions, one of "before-headers", "after-request", or "on-shutdown"</td>
  <td>after-request</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>
</deftable>

<def title="&lt;session-config> schema">
element session-config {
  always-load-session?
  &amp; always-save-session?
  &amp; cookie-append-server-index?
  &amp; cookie-domain?
  &amp; cookie-length?
  &amp; cookie-max-age?
  &amp; cookie-port?
  &amp; cookie-secure?
  &amp; cookie-version?
  &amp; enable-cookies?
  &amp; enable-url-rewriting?
  &amp; ignore-serialization-errors?
  &amp; invalidate-after-listener?
  &amp; reuse-session-id?
  &amp; save-mode?
  &amp; save-on-shutdown?
  &amp; serialization-type?
  &amp; session-max?
  &amp; session-timeout?
  &amp; use-persistent-store?
}
</def>

<p>The <var>session-timeout</var> and <var>session-max</var> 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 <var>session-max</var>, the
oldest sessions are recovered.  In addition, sessions idle for
longer than <code>session-timeout</code> are purged.</p>

<example title="using session-config and session-timeout to control the number of sessions">
&lt;web-app id='/dir'&gt;

  &lt;session-config&gt;
     &lt;!-- 2 hour timeout --&gt;
     &lt;session-timeout&gt;120&lt;/session-timeout&gt;
     &lt;session-max&gt;4096&lt;/session-max&gt;
  &lt;/session-config&gt;

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


<p><var>cookie-length</var> 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.</p>

<p><var>reuse-session-id</var> defaults to true so that Resin can share the session
id amongst different web-apps.</p>

<p>The class that corresponds to &lt;session-config&gt; is <a href="javadoc|com.caucho.server.session.SessionManager|"/></p>

</defun>

<defun title="&lt;shutdown-wait-max>" version="Resin 3.0.4" type="defun">
<p>The maximum time Resin will wait for requests to finish before closing the web-app.</p>
<default>15s</default>

<def title="&lt;shutdown-wait-max> schema">
element shutdown-wait-max {
  r_period-Type
}
</def>

</defun>

<defun title="&lt;statistics-enable>">
<default>false</default>

<p>&lt;statistics-enable> enables more detailed statistics for the
<code>WebAppMXBean</code> administration.  The statistics gathering
is disabled by default for performance reasons.</p>

<def title="&lt;statistics-enable> schema">
element statistics-enable {
  r_boolean-Type
}
</def>

</defun>

<defun title="&lt;strict-mapping>" version="Resin 1.2" type="defun">
<default>false, allowing /foo/bar.jsp/foo.</default>
<p>Forces servlet-mapping to follow strict Servlet 2.2, disallowing
PATH_INFO. Value is <var>true</var> or <var>false</var>.</p>

<def title="&lt;strict-mapping> schema">
element strict-mapping {
  r_boolean-Type
}
</def>

<example title="Example: enabling strict-mapping in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;strict-mapping&gt;true&lt;/strict-mapping&gt;
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;user-data-constraint>" version="Servlet" type="defun">
<parents>security-constraint</parents>

<p>Restricts access to secure transports, such as SSL</p>

<deftable title="&lt;user-data-constraints> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>transport-guarantee</td>
  <td>Required transport properties.  NONE,
INTEGRAL, and CONFIDENTIAL are allowed values.</td>
</tr>
</deftable>

<def title="&lt;user-data-constraint> schema">
element user-data-constraint {
  transport-guarantee
}
</def>

</defun>

<defun title="&lt;web-app>" type="defun">
<parents>host, web-app</parents>

<p>web-app configures a web application.</p>

<deftable-childtags>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>active-wait-time</td>
  <td>how long a thread should wait for the web-app to initialize before returning a 503-busy.</td>
  <td>15s</td>
</tr>
<tr>
  <td>archive-path</td>
  <td>Specifies the location of the web-app's .war file.</td>
  <td>n/a</td>
</tr>
<tr>
  <td>context-path</td>
  <td>Specifies the URL prefix for the web-app.</td>
  <td>the <var>id</var> value</td>
</tr>
<tr>
  <td>id</td>
  <td>The url prefix selecting this application.</td>
  <td>n/a</td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>'automatic' or 'manual', see <a href="resin-tags.xtp#startup-mode">Startup and Redeploy Mode</a></td>
  <td>automatic</td>
</tr>
<tr>
  <td>redeploy-check-interval</td>
  <td>how often to check the .war archive for redeployment</td>
  <td>60s</td>
</tr>
<tr>
  <td>root-directory</td>
  <td>The root directory for the application, corresponding to a url of <var>/<i>id</i>/</var>. A relative path is relative to the <a config-tag="root-directory"/> of the containing <a config-tag="host"/>.  Can use regexp replacement variables.</td>
  <td>A relative path constricted with the id or the regexp match</td>
</tr>
<tr>
  <td>startup-mode</td>
  <td>'automatic', 'lazy', or 'manual', see <a href="resin-tags.xtp#startup-mode">Startup and Redeploy Mode</a></td>
  <td>automatic</td>
</tr>
<tr>
  <td>startup-priority</td>
  <td>specifies a priority for web-app startup to force an ordering between webapps </td>
  <td>-1</td>
</tr>
<tr>
  <td>url-regexp</td>
  <td>A regexp to select this application.</td>
  <td>n/a</td>
</tr>
</deftable-childtags>

<p>When specified by <var>id</var>, the application will be initialized on
server start.  When specified by <var>url-regexp</var>, the application
will be initialized at the first request.  This means that
<var>load-on-startup</var> servlets may start later than expected for
<var>url-regexp</var> applications.</p>

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

<example>
&lt;host id=''&gt;
  &lt;web-app id='/apache' document-directory='/usr/local/apache/htdocs'&gt;

  ...

&lt;/host&gt;
</example>

<p>The following example sets the root web-app to the IIS
root directory. </p>

<example>
  &lt;web-app id='/' document-directory='C:/inetpub/wwwroot'&gt;
</example>

<p>When the <var>web-app</var> is specified with a <var>url-regexp</var>,
<var>document-directory</var> can use replacement variables (<var>$2</var>).</p>

<p>In the following, each user gets his or her own independent
application using <var>~user</var>.</p>

<example>
&lt;host id=''&gt;

  &lt;web-app url-regexp='/~([^/]*)'
           document-directory='/home/$1/public_html'&gt;

    ...

  &lt;/web-app&gt;

&lt;/host&gt;
</example>

</defun>

<defun title="&lt;web-app-default>" type="defun">
<parents>cluster, host, web-app</parents>
      
<p>Establishes the defaults for a <a config-tag="web-app"/>.</p>

<p>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.</p>

<p>web-app-default is used for defining server-wide behavior, like *.jsp
handling, and for host-wide behavior.</p>

<example>
&lt;host&gt;
  &lt;web-app-default&gt;
    &lt;servlet servlet-name='test'
             servlet-class='test.MyServlet'/&gt;

    &lt;servlet-mapping url-pattern='*.text' servlet-class='test'/&gt;
  &lt;/web-app-default&gt;
&lt;/host&gt;
</example>

</defun>

<defun title="&lt;web-app-deploy>" type="defun">
<parents>host, web-app</parents>

<p>Specifies war expansion.</p>

<p>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.</p>

<deftable title="&lt;web-app-deploy> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-directory</td>
  <td>directory containing the .war files</td>
  <td>value of <var>path</var></td>
</tr>
<tr>
  <td>dependency-check-interval</td>
  <td>How often to check the .war files for a redeploy</td>
  <td>60s</td>
</tr>
<tr>
  <td>expand-cleanup-fileset</td>
  <td>defines the files which should be automatically deleted
when an updated .war expands</td>
  <td>all files</td>
</tr>
<tr>
  <td>expand-directory</td>
  <td>directory where wars should be expanded</td>
  <td>value of <var>path</var></td>
</tr>
<tr>
  <td>expand-prefix</td>
  <td>prefix string to use when creating the expansion directory, e.g. _war_</td>
  <td></td>
</tr>
<tr>
  <td>expand-suffix</td>
  <td>prefix string to use when creating the expansion directory, e.g. .war</td>
  <td></td>
</tr>
<tr>
  <td>path</td>
  <td>The path to the webapps directory</td>
  <td>required</td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>"automatic" or "manual"</td>
  <td>automatic</td>
</tr>
<tr>
  <td>require-file</td>
  <td>additional files to use for dependency checking for auto restart</td>
  <td></td>
</tr>
<tr>
  <td>startup-mode</td>
  <td>"automatic", "lazy" or "manual"</td>
  <td>automatic</td>
</tr>
<tr>
  <td>url-prefix</td>
  <td>url-prefix added to all expanded webapps</td>
  <td>""</td>
</tr>
<tr>
  <td>versioning</td>
  <td>if true, use the web-app's numeric suffix as a version</td>
  <td>false</td>
</tr>
<tr>
  <td>web-app-default</td>
  <td>defaults to be applied to expaned web-apps</td>
  <td></td>
</tr>
<tr>
  <td>web-app</td>
  <td>overriding configuration for specific web-apps</td>
  <td></td>
</tr>
</deftable>

<def title="&lt;web-app-deploy> schema">
element web-app-deploy {
  archive-directory?
  expand-cleanup-fileset?
  expand-directory?
  expand-prefix?
  expand-suffix?
  path?
  redeploy-check-interval?
  redeploy-mode?
  require-file*
  startup-mode?
  url-prefix?
  versioning?
  web-app-default*
  web-app*
}
</def>

<s2 title="Overriding web-app-deploy configuration">

<p>The web-app-deploy can override configuration for an expanded war with
a matching &lt;web-app&gt; inside the &lt;web-app-deploy&gt;.  The
&lt;document-directory&gt; is used to match web-apps.</p>

<example title="Example: resin.xml overriding web.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">
&lt;host id="">

&lt;web-app-deploy path="webapps"&gt;
  &lt;web-app context-path="/wiki"
              document-directory="wiki"&g