config-webapp.xtp

RESIN 3.2 最新源码

<p>By default, both <code>enable-cookies</code> and
<code>enable-url-rewriting</code> are true. To force url rewriting, you
would create a configuration like:</p>

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

  &lt;session-config
   enable-cookies='false'
   enable-url-rewriting='true'/&gt;

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

<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>

</s2>

<s2 title="mime-mapping" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>
<p>Maps url patterns to mime-types.</p>

<deftable-childtags>
<tr><td>extension</td><td>url extension
</td></tr><tr><td>mime-type</td><td>the mime-type
</td></tr></deftable-childtags>

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

  &lt;mime-mapping&gt;
    &lt;extension&gt;.foo&lt;/extension&gt;
    &lt;mime-type&gt;text/html&lt;/mime-type&gt;
  &lt;/mime-mapping&gt;

  &lt;!-- resin shortcut syntax --&gt;
  &lt;mime-mapping extension='.bar'
                mime-type='text/html'/&gt;

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

<p>Resin has a long list of default mime types in <var>$RESIN_HOME/conf/app-default.xml</var></p>
</s2>

<s2 title="welcome-file-list" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>
<default>in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.</default>

<p>Sets the files to use as when no filename is present in
url. According to the spec, each file is in a &lt;welcome-file&gt;
element.</p>

<example>
&lt;web-app id='/'&gt;
  &lt;welcome-file-list&gt;
    &lt;welcome-file&gt;index.jsp&lt;/welcome-file&gt;
    &lt;welcome-file&gt;index.xtp&lt;/welcome-file&gt;
    &lt;welcome-file&gt;home.xtp&lt;/welcome-file&gt;
  &lt;/welcome-file-list&gt;
&lt;/web-app&gt;
</example>

<p>Resin also provides a shortcut where you can just list the files:</p>

<example>
&lt;web-app id='/'&gt;
  &lt;welcome-file-list&gt;
    index.jsp, index.xtp, home.xtp
  &lt;/welcome-file-list&gt;
&lt;/web-app&gt;
</example>

</s2>

<s2 title="error-page" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>

<deftable-childtags>
<tr><td>error-code</td><td>Select the error page based on an HTTP status code
</td></tr><tr><td>exception-type</td><td>Select the error page based on a Java exception
</td></tr><tr><td>location</td><td>The error page to display
</td></tr></deftable-childtags>

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

<example title="Catching File Not Found">
&lt;web-app&gt;
  &lt;error-page&gt;
    &lt;error-code&gt;404&lt;/error-code&gt;
    &lt;location&gt;/file_not_found.jsp&lt;/location&gt;
  &lt;/error-page&gt;
&lt;/web-app&gt;
</example>

<example title="Catching Exceptions">
&lt;web-app id='/foo'&gt;
      &lt;error-page exception-type='java.lang.NullPointerException'
                  location='/nullpointer.jsp'/&gt;
&lt;/web-app&gt;
</example>

<p>The error page can use request attributes to obtain information about the
request that caused the error:</p>

<example title="/file_not_found.jsp">
&lt;%@ page session="false" isErrorPage="true" %&gt;

&lt;html&gt;
&lt;head&gt;&lt;title&gt;404 Not Found&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;
&lt;h1&gt;404 Not Found&lt;/h1&gt;

The url &lt;code&gt;${'${'}requestScope["javax.servlet.error.request_uri"]}&lt;/code&gt; 
was not found.
&lt;/body&gt;
&lt;/html&gt;
</example>

<s3 title="Request attributes for error handling">

<deftable>
<tr><th>Attribute</th><th>Type
</th></tr><tr><td>javax.servlet.error.status_code</td><td>java.lang.Integer
</td></tr><tr><td>javax.servlet.error.message</td><td>java.lang.String
</td></tr><tr><td>javax.servlet.error.request_uri</td><td>java.lang.String
</td></tr><tr><td>javax.servlet.error.servlet_name</td><td>java.lang.String
</td></tr><tr><td>javax.servlet.error.exception</td><td>java.lang.Throwable
</td></tr><tr><td>javax.servlet.error.exception_type</td><td>java.lang.Class
</td></tr></deftable>

</s3>

</s2>

<s2 title="jsp-config" version="Servlet" type="defun">
</s2>

<s2 title="resource-env-ref" version="Servlet" type="defun">
</s2>

<s2 title="message-destination-ref" version="Servlet" type="defun">
</s2>

<s2 title="resource-ref" version="Servlet" type="defun">
</s2>

<s2 title="security-constraint" version="Servlet" type="defun">
<parents>web-app-default, web-app</parents>

<p>Specifies protected areas of the web site.  Sites using
authentication as an optional personalization feature will typically
not use any security constraints.</p>

<p>Security constraints can also be custom classes.</p>

<example>
&lt;security-constraint&gt;
  &lt;web-resource-collection&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  &lt;/web-resource-collection&gt;
  &lt;auth-constraint role-name='user'&gt;
&lt;/security-constraint&gt;
</example>
</s2>

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

<s2 title="web-resource-collection" version="Servlet" type="defun">
<parents>security-constraint</parents>

<p>Specifies a collection of areas of the web site.</p>

<deftable-childtags>
<tr><td>web-resource-name</td><td>a name for a web resource collection
</td></tr><tr><td>description</td><td>
</td></tr><tr><td>url-pattern</td><td>url patterns describing the resource
</td></tr><tr><td>http-method</td><td>HTTP methods to be restricted.
</td></tr><tr><td>method</td><td>
</td></tr></deftable-childtags>
</s2>

<s2 title="auth-constraint" version="Servlet" type="defun">
<parents>security-constraint</parents>

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

<deftable-childtags>
<tr><td>role-name</td><td>Roles which are allowed to access the resource.
</td></tr></deftable-childtags>

</s2>

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

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

<deftable-childtags>
<tr><td>transport-guarantee</td><td>Required transport properties.  NONE,
INTEGRAL, and CONFIDENTIAL are allowed values.
</td></tr></deftable-childtags>

</s2>

<s2 title="constraint" version="Resin" type="defun">
<parents>security-constraint</parents>

<p>
Defines a custom constraint.
</p>

<deftable-childtags>
<tr><td>resin:type</td><td>A class that extends <a href="javadoc|com.caucho.http.security.AbstractConstraint|"/>
</td></tr><tr><td>init</td><td>initialization parameters, set in the object using Bean-style setters and getters
</td></tr></deftable-childtags>

</s2>

<s2 title="login-config" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>
<default>no authentication</default>

<deftable-childtags title="Servlet 2.4 definition for login-config">
<tr><td>auth-method</td><td>Authentication method, either <var>BASIC</var> for HTTP Basic Authentication, <var>FORM</var> for form based authentication, or <var>DIGEST</var> for HTTP <a href="security-digest.xtp">Digest Authentication</a>.
</td></tr><tr><td>realm-name</td><td>The realm name to use in HTTP authentication
</td></tr><tr><td>form-login-config</td><td>Configuration for form login, see <a config-tag="form-login-config"/>
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to login-config">
<tr><td>type</td><td>Defines a custom class which extends <code>com.caucho.server.security.AbstractLogin</code>
</td></tr><tr><td>init</td><td>Initialization for the custom login class
</td></tr></deftable-childtags>


<p>HTTP Authentication is defined in the RFC <a href="http://www.faqs.org/rfcs/rfc2617.thml">HTTP Authentication: Basic and
Digest</a>.</p> 

<p>HTTP digest authentication is discussed in <a href="security-digest.xtp">Digest Passwords</a>.

</p></s2>


<s2 title="form-login-config" version="Servlet" type="defun">
<parents>login-config</parents>

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

<deftable-childtags title="Servlet 2.4 definition for form-login-config">
<tr><td>form-login-page</td><td>The page to be used to prompt the user login</td><td>none
</td></tr><tr><td>form-error-page</td><td>The error page for unsuccessful login</td><td>none
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to form-login-config">
<tr><td>internal-forward</td><td>Use an internal redirect on success instead of a sendRedirect</td><td>false
</td></tr><tr><td>form-uri-priority</td><td>If true, the form's j_uri will override a stored URI</td><td>false
</td></tr></deftable-childtags>

<p>The form itself must have the action <var>j_security_check</var>.  It
must also have the parameters <var>j_username</var> and <var>j_password</var>.
Optionally, it can also have <var>j_uri</var> and
<var>j_use_cookie_auth</var>.  <var>j_uri</var> gives the next page to display
when login succeeds.  <var>j_use_cookie_auth</var> allows Resin to send a
persistent cookie to the user to make following login easier.</p>

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

<deftable-childtags>
<tr><td>j_security_check</td><td>The form's mandatory action
</td></tr><tr><td>j_username</td><td>The user name
</td></tr><tr><td>j_password</td><td>The password
</td></tr><tr><td>j_uri</td><td>Optional Resin extension for the successful display page.
</td></tr><tr><td>j_use_cookie_auth</td><td>Optional Resin extension to allow cookie login.
</td></tr></deftable-childtags>

<p>The following is an example of a servlet-standard login page:</p>

<example>
&lt;form action='j_security_check' method='POST'&gt;
&lt;table&gt;
&lt;tr&gt;&lt;td&gt;User:&lt;td&gt;&lt;input name='j_username'&gt;
&lt;tr&gt;&lt;td&gt;Password:&lt;td&gt;&lt;input name='j_password'&gt;
&lt;tr&gt;&lt;td colspan=2&gt;hint: the password is 'quidditch'
&lt;tr&gt;&lt;td&gt;&lt;input type=submit&gt;
&lt;/table&gt;
&lt;/form&gt;
</example>

</s2>

<s2 title="security-role" version="Servlet" type="defun">
</s2>

<s2 title="env-entry" version="Servlet" type="defun">
</s2>

<s2 title="ejb-ref" version="Servlet" type="defun">
<parents>web-app-default, web-app</parents>
</s2>

<s2 title="ejb-local-ref" version="Servlet" type="defun">
<parents>web-app-default, web-app</parents>
</s2>

<s2 title="message-destination" version="Servlet" type="defun">
</s2>

<s2 title="locale-encoding-mapping-list" version="Servlet" type="defun">
</s2>
</s1>
</body>

</document>