webapp-tags.xtp

RESIN 3.2 最新源码

  automatic | manual
}
</def>

</defun>

<defun title="Resource Tags" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<p>See the <a href="env-tags.xtp">Resource tag documentation</a> for
 a full list of resources available to the web-app.</p>

<p>All resource tags are available to
the &lt;web-app>, like databases, IoC beans and components, EJB stateful,
stateless and message beans, JMS queues, remote clients, etc.</p>

<example title="Example: web-app database in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;database jndi-name="jdbc/test"&gt;
    &lt;driver type="org.postgresql.Driver"&gt;
      &lt;url&gt;jdbc:postgresql://localhost/test&lt;/url&gt;
      &lt;user&gt;caucho&lt;/user&gt;
    &lt;/driver&gt;
  &lt;/database&gt;
&lt;/web-app&gt;
</example>

<p>Or <a href="ioc-bean.xtp">IoC-configured Beans</a>:</p>

<example title="Example: IoC bean in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;bean jndi-name="jdbc/test" type="example.Theater&gt;
    &lt;init name="Balboa Theater">
      &lt;movie title="Attack of the Killer Tomatoes"/>

      &lt;movie title="Snakes on a Plane"/>

      &lt;movie title="Casablanca"/>
    &lt;/init>
  &lt;/bean>
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;rewrite-dispatch>" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<p>&lt;rewrite-dispatch&gt; defines a set of rewriting rules for
dispatching and forwarding URLs.  Applications can use these rules
to redirect old URLs to their new replacements.</p>

<p>See <a href="rewrite-tags.xtp">rewrite-dispatch</a> for more
details.</p>

<example title="Example: Mediawiki dispatch in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

 &lt;rewrite-dispatch>
   &lt;dispatch regexp="\.(php|gif|css|jpg|png)"/>
   &lt;forward regexp="^" target="/index.php"/>
 &lt;/rewrite-dispatch>

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

</defun>

<defun title="&lt;rewrite-real-path>" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<p>&lt;rewrite-real-path> lets you rewrite the URL to physical path
mapping, to allow aliasing or for filesystem organization.</p>

<deftable title="&lt;rewrite-real-path> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>real-path</td>
  <td>specifies the URL to real-path mapping</td>
</tr>
<tr>
  <td>regexp</td>
  <td>a regular expression matching a URL</td>
</tr>
<tr>
  <td>replacement</td>
  <td>specifies a replacement pattern for URL to URL rewriting</td>
</tr>
<tr>
  <td>rewrite</td>
  <td>rewrites a URL to another URL as a preprocessing-step</td>
</tr>
<tr>
  <td>target</td>
  <td>specifies the target for URL to real-path mapping</td>
</tr>
</deftable>

<def title="&lt;rewrite-real-path> schema">
element rewrite-real-path {
  element rewrite {
    regexp
    &amp; replacement
  }*

  &amp; element rewrite {
    regexp
    &amp; target
  }*
}
</def>

<example title="Example: aliasing /foo to /bar">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;rewrite-real-path>
    &lt;real-path regexp="^/foo" target="/bar"/>
  &lt;/rewrite-real-path>

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

</defun>

<defun title="&lt;root-directory>" version="Resin 3.1">

<p>&lt;root-directory> configures the web-app's filesystem root.</p>

<def title="&lt;root-directory> schema">
element root-directory {
  string
}
</def>

</defun>

<defun title="&lt;secure>">
<parents>web-app</parents>

<p>The &lt;secure> flag requires that the web-app only be accessed
in a secure/SSL mode.  Equivalent to a &lt;security-constraint>.</p>

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

</defun>

<defun title="&lt;security-constraint>" version="Servlet">
<parents>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.  See <a href="resin-security.xtp">Resin
security</a> for an overview.</p>

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

<p>See <a href="resin-security.xtp">Resin security</a> for an overview of
security issues and configuration.</p>

<deftable title="&lt;security-constraint> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>auth-constraint</td>
  <td>Defines a security condition based on a logged-in user's role</td>
</tr>
<tr>
  <td>constraint</td>
  <td>Defines a custom security condition</td>
</tr>
<tr>
  <td>ip-constraint</td>
  <td>Defines a security condition based the remote IP address</td>
</tr>
<tr>
  <td>role-name</td>
  <td>Defines role-name requirement</td>
</tr>
<tr>
  <td>url-pattern</td>
  <td>URL pattern to match the security constraint</td>
</tr>
<tr>
  <td>user-data-constraint</td>
  <td>Defines SSL or non-SSL requirements</td>
</tr>
<tr>
  <td>web-resource-collection</td>
  <td>URL patterns and HTTP methods defining the constraint</td>
</tr>
</deftable>

<def title="&lt;security-constraint> content">
element security-constraint {
  auth-constraint*
  &amp; constraint*
  &amp; ip-constraint*
  &amp; role-name*
  &amp; user-data-constraint*
  &amp; url-pattern?
  &amp; web-resource-collection*
}
</def>

<example title="Example: 'user' role required in WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

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

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

<defun title="&lt;servlet>" version="Servlet 2.2">

<p>Defines a servlet to process HTTP URL requests.  The servlet class
can either implement <a href="http://caucho.com/resin-javadoc/javax/servlet/Servlet.html">javax.servlet.Servlet</a> to handle the HTTP request
directly or it can use a <a href="resin-remoting.xtp">remoting</a>
protocol like SOAP or Hessian to handle remoting requests.</p>

<p>Since servlets are full <a href="resin-ioc.xtp">Resin-IoC</a> beans,
they can use dependency injection, EJB aspects like @TransactionAttribute,
custom @InterceptorType interceptors, and listen for @Observes events.</p>

<deftable title="&lt;servlet> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>init</td>
  <td><a href="resin-ioc.xtp">Resin-IoC</a> initialization</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>protocol</td>
 <td>Protocol configuration for <a href="resin-remoting.xtp">Resin remoting</a>.</td>
</tr>
<tr>
  <td>run-at</td>
  <td>Times to execute the servlet automatically.</td>
</tr>
<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>
</deftable>

<def title="&lt;servlet> schema">
element servlet {
  servlet-name
  &lt; (servlet-class | jsp-file)
  &lt; init*
  &lt; init-param*
  &lt; load-on-startup?
  &lt; protocol?
  &lt; run-as?
  &lt; run-at?
}
</def>

<example title="Example: WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns">

  &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="Example: multiple servlets using the same class">
&lt;web-app xmlns="http://caucho.com/ns/resin"&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="Example: servlet-mappings 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>
</defun>

<defun title="&lt;servlet-mapping>" version="Servlet 2.2">
<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 title="&lt;servlet-mapping> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>init</td>
  <td><a href="resin-ioc.xtp">Resin-IoC</a> configuration of the
servlet.</td>
</tr>
<tr>
  <td>protocol</td>
  <td>Defines the optional <a href="resin-remoting.xtp">remoting</a>
protocol.</td>
</tr>
<tr>
  <td>servlet-class</td>
  <td>The servlet-mapping can define the servlet directly as a shortcut.</td>
</tr>
<tr>
  <td>servlet-name</td>
  <td>The servlet 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>url-regexp</td>
  <td>A regular expression matching the portion of the url that follows the <g>context path</g></td>
</tr>
</deftable>

<def title="&lt;servlet-mapping> schema">
element servlet-mapping {
  init?
  &amp; protocol?
  &amp; servlet-class?
  &amp; servlet-name?
  &lt; url-pattern*
  &lt; url-regexp*
}
</def>

<example title="Example: WEB-INF/resin-web.xml &lt;servlet-mapping>">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &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>
<code>url-regexp</code> matches the portion of the url that follows the <g>context path</g>.  
A webapp in <code>webapps/ROOT</code>, and a url
<code>http://localhost/foo/hello.html</code> will have a value of <code>"/foo/hello.html"</code> for the
purposes of the regular expression match.
A webapp in <code>webapps/baz</code> and a url
<code>http://localhost/baz/hello.html</code> will have a url of <code>"/hello.html"</code> for the
purposes of the regular expression match, because "/baz" is the context path.
</p>

<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="Example: WEB-INF/resin-web.xml servlet invoker">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &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="Example: servlet-mappings in $RESIN_HOME/conf/app-default.xml">
&lt;cluster>

&lt;web-app-default>
  &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;
&lt;/web-app-default>
&lt;/cluster>
</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>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<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>
</defun>

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

<def title="&lt;servlet-regexp> schema">