servlet.xtp

RESIN 3.2 最新源码

<p>The usual case balances all requests to backend servers.  The front-end Resin
instance has a resin.xml similar to the one shown here.  It configures
the front-end instance to balance the load to the backend
servers.  The backend Resin instances have a resin.xml file that
configures the web site, similar to a conf file that is used when only one
instance of Resin used for the server.</p>

<example title="frontend.conf">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;server&gt;

    &lt;http id='frontend' port='8080'/&gt;

    &lt;cluster id='backend'&gt;
      &lt;srun id='a' host='192.168.0.11' port='6810'/&gt;
      &lt;srun id='b' host='192.168.0.12' port='6810'/&gt;
    &lt;/cluster&gt;

    &lt;!-- the front-end does the access logging --&gt;
    &lt;access-log path='log/access.log'&gt;
      &lt;rollover-period&gt;2W&lt;/rollover-period&gt;
    &lt;/access-log&gt;

    &lt;!-- all urls are load balanced to the backend --&gt;
    &lt;host id=''&gt;
      &lt;web-app id='/'&gt;
        &lt;servlet&gt;
          &lt;servlet-name&gt;backend&lt;/servlet-name&gt;
          &lt;servlet-class&gt;com.caucho.servlets.LoadBalanceServlet&lt;/servlet-class&gt;
          &lt;init&gt;
            &lt;cluster&gt;backend&lt;/cluster&gt;
          &lt;/init&gt;
        &lt;/servlet&gt;

        &lt;servlet-mapping url-pattern='/*' servlet-name='backend'/&gt;
      &lt;/web-app&gt;
   &lt;/host&gt;
  &lt;/server&gt;
&lt;/resin&gt;
</example>

<p>LoadBalanceServlet is also used to allow a separate JVM for a web-app or a
host.</p>

<p>
The <var>strategy</var> determines the strategy to use for choosing a backend
server for a request that does not have a sticky-session.  The
`least-connection' strategy chooses the backend server that has the least
number of connections at the time the decision is made.  This is a good general
purpose strategy, and compensates for differences in a backend server's ability
to service connections.  The `round-robin' strategy does a straight round
robin, choosing the backend server that follows the last backend server chosen.
</p>

<p>
See <a href="javadoc|com.caucho.servlets.LoadBalanceServlet|"/>.
</p>
</s1>

<s1 title="CGIServlet">

<p>Implements CGI calls.  The url is assumed to refer to an executable file,
and the operating system is instructed to execute the program or script.  The
usual CGI environment variables are set, and the current directory is 
the value of <code>$RESIN_HOME</code></p>

<deftable-parameters>
<tr><td>executable</td><td>Path to the script program</td><td>default exec
</td></tr><tr><td>ignore-exit-code</td><td>If true, do not treat a non-zero exit code as an error</td><td>false
</td></tr><tr><td>stderr-is-exception</td><td>If false, ignore output on stderr instead of triggering an exception</td><td>true
</td></tr></deftable-parameters>

<example title="WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;cgi&lt;/servlet-name&gt;
    &lt;servlet-class&gt;com.caucho.servlets.CGIServlet&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping servlet-name="cgi" url-pattern="/cgi-bin/*.exe"/&gt;
&lt;/web-app&gt;
</example>

<p>
The <code>servlet-mapping</code> specifies the requests that will be treated as
CGI exectutables.  In the example above, only files in the /cgi-bin directory
with an extension of ".exe" will be executed.  It is important to limit the
url-pattern as much as possible to avoid allowing unintended execution of
scripts or binaries on the system.
</p>

<p>
A CGI script must output a blank line between the HTTP header(s) and the
rest of the response.  If no blank line is encountered, the contents of your
browser page will be blank.  Usually a CGI script will output a
<code>Content-Type:</code> header and then a blank line before the content:
</p>

<example title="Minimal CGI script">
#!/bin/sh

echo "Content-Type: text/html"
echo
echo "&lt;h&gt;CGI Test&lt;h1&gt;"
echo "CGI Test"

echo "&lt;pre&gt;"
env
echo "&lt;/pre&gt;"

</example>

</s1>

<s1 title="DirectoryServlet">

<p>The directory servlet provides the basic directory browsing.
The servlet-name must be "directory" for the servlet to take effect.
Sites will normally disable it.</p>

<deftable-parameters>
<tr>
  <td>enable</td>
  <td>Enable or disable the servlet</td>
  <td>true</td>
</tr>
</deftable-parameters>

<example>
&lt;servlet servlet-name="directory"
         servlet-class="com.caucho.servlets.DirectoryServlet"&gt;
  &lt;init enable="false"/&gt;
&lt;/servlet&gt;
</example>

</s1>

<s1 title="FastCGIServlet">

<p>Implements the FastCGI protocol.  FastCGI allows some CGI clients
like PHP to run quicker and more efficiently.</p>

<deftable-parameters>
<tr><td>server-address</td><td>the host and port number, in the form host:port</td><td>required
</td></tr></deftable-parameters>

<p>
The FastCGIServlet creates a socket connection from Resin to the backend
program that supports the fastcgi protocol.  <a config-tag="servlet-mapping"/>
is used to configure the filename patterns of scripts that are handled by the
backend program.
</p>

<p>
The following example configures Resin so that any files within a single webapp
matching the pattern"*.php" are handled by the backend program:
</p>

<example title="WEB-INF/web.xml">
&lt;web-app&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;php-fastcgi&lt;/servlet-name&gt;
    &lt;servlet-class&gt;com.caucho.servlets.FastCGIServlet&lt;/servlet-class&gt;
    &lt;init&gt;
      &lt;server-address&gt;localhost:6666&lt;/server-address&gt;
    &lt;/init&gt;
  &lt;/servlet&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;php-fastcgi&lt;/servlet-name&gt;
    &lt;url-pattern&gt;*.php&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</example>

<p>Assuming PHP has been compiled with -fastcgi enabled, you might
start PHP like:</p>

<example>
unix&gt; php -b 6666 
</example>

<p>
Mapping is enabled for all web-apps with the use of 
<a config-tag="web-app-default"/>.  In this example, filenames with the pattern
"*.php" and the pattern "*.phtml" are handled by the backend program: 
</p>

<example title="resin.xml">
&lt;web-app-default&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;php-fastcgi&lt;/servlet-name&gt;
    &lt;servlet-class&gt;com.caucho.servlets.FastCGIServlet&lt;/servlet-class&gt;
    &lt;init&gt;
      &lt;server-address&gt;localhost:6666&lt;/server-address&gt;
    &lt;/init&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping url-pattern="*.php"   servlet-name="php-fastcgi"/&gt;
  &lt;servlet-mapping url-pattern="*.phtml" servlet-name="php-fastcgi"/&gt;

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

<p>See <a href="javadoc|com.caucho.servlets.FastCGIServlet|"/>.</p>
</s1>

<s1 title="HttpProxyServlet">

<p>
<a href="javadoc|com.caucho.servlets.HttpProxyServlet|"/> is a servlet that
proxies to another server.  This can be useful for providing access to legacy
backend servers.
</p>

<example title="HttpProxyServlet">
  &lt;servlet&gt;
    &lt;servlet-name&gt;http-proxy&lt;/servlet-name&gt;
    &lt;servlet-class&gt;com.caucho.servlets.HttpProxyServlet&lt;/servlet-class&gt;
    &lt;init host='localhost:8081'/&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping url-pattern="/foo/*" servlet-name="http-proxy"/&gt;
  &lt;servlet-mapping url-pattern="/bar/*" servlet-name="http-proxy"/&gt;
</example>


<p>
There is a bit more power using servlet-regexp and regular expressions:
</p>

<example title="HttpProxyServlet with regexp">
&lt;servlet-regexp url-regexp="^/foo(/.*)?"
                servlet-class="com.caucho.servlets.HttpProxyServlet"&gt;
  &lt;init host='localhost:8081'/&gt;
&lt;/servlet-regexp&gt;
</example>
</s1>

<s1 title="SSIServlet">

<p>
<a href="javadoc|com.caucho.servlets.ssi.SSIServlet|"/> is a servlet that
processes server side include directives.  The syntax for server side includes
is the same as the syntax used in <a href="http://httpd.apache.org/docs/1.3/mod/mod_include.html">Apache httpd</a>.
</p>

<example title="resin-web.xml SSIServlet">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;servlet-mapping url-pattern="*.shtml"
                   servlet-class="com.caucho.servlets.ssi.SSIServlet"/&gt;
&lt;/web-app&gt;
</example>

<example title="test.shtml">
&lt;h1&gt;A little test&lt;/h1&gt;

&lt;!--#config timefmt="%Y-%m-%d" --&gt;
&lt;!--#echo var="DATE_GMT" --&gt;

&lt;!--#include virtual="inc.jsp" --&gt;

&lt;!--#set var="a" value="$REQUEST_METHOD" --&gt;
&lt;!--#include virtual="inc.jsp?q=$a" --&gt;

</example>
</s1>

<s1 title="WebDAVServlet">

<p>WebDAV, web-based distributed authoring and versioning, is a set
of extensions to the HTTP protocol that is a convenient replacement
for FTP when developing web sites.  Many editing tools can save to a
WebDAV server directly and several operating systems can provide a
filesystem to a WebDAV server.</p>

<p>From <a href="http://www.webdav.org">www.webdav.org</a>:
</p><blockquote>
<b>What is WebDAV?</b><br/>

Briefly: WebDAV stands for "Web-based Distributed Authoring and Versioning".
It is a set of extensions to the HTTP protocol which allows users to
collaboratively edit and manage files on remote web servers.
</blockquote>

<p>The WebDAV site also contains pointers to programs which
understand WebDAV.</p>

<p>The WebDAV servlet must be enabled explicitly.  By default, it also
requires a logged in user playing the 'webdav' role and requires a
secure (SSL) connection.  These can be relaxed, but having
the defaults require security makes it unlikely that a webmaster will
enable WebDAV by mistake.</p>

<deftable-parameters>
<tr><td>enable</td><td>Enable webdav servlet for read ("read") or read/write ("write")</td><td>false (disabled)
</td></tr><tr><td>role</td><td>The role required for webdav, '*' means no role required</td><td>webdav
</td></tr><tr><td>user</td><td>A specific user required for webdav</td><td>none
</td></tr><tr><td>secure</td><td>If true, only allow updates over a secure connection
(SSL)</td><td>true
</td></tr><tr><td>root</td><td>Configures the root directory for webdav</td><td>The application root
</td></tr><tr><td>path-source</td><td>The jndi name of a custom path backing previously defined as a resource.  This allows a custom path backing, e.g. a database source</td><td>an instance of  <a href="javadoc|com.caucho.servlets.webdav.ApplicationPath|"/>

</td></tr></deftable-parameters>


<p>The following example is a typical WebDAV configuration.  The explicit
servlet-mapping and setting <var>enable</var> to 'write' is necessary.  Since
<var>secure</var> is left as the default, it will require an SSL connection.</p>

<example title="Enabling WebDAV">
&lt;servlet&gt;
  &lt;servlet-name&gt;webdav&lt;/servlet-name&gt;
  &lt;servlet-class&gt;com.caucho.servlets.webdav.WebDavServlet&lt;/servlet-class&gt;
  &lt;init&gt;
    &lt;enable&gt;write&lt;/enable&gt;
  &lt;/init&gt;
&lt;/servlet&gt;

&lt;servlet-mapping url-pattern='/webdav/*' servlet-name='webdav'/&gt;

&lt;authenticator&gt;
  &lt;type&gt;com.caucho.server.security.XmlAuthenticator&lt;/type&gt;
  &lt;init&gt;
    &lt;user&gt;Harry Potter:quidditch:webdav&lt;/user&gt;
    &lt;password-digest&gt;none&lt;/password-digest&gt;
  &lt;/init&gt;
&lt;/authenticator&gt;

&lt;login-config&gt;
  &lt;auth-method&gt;basic&lt;/auth-method&gt;
&lt;/login-config&gt;

&lt;security-constraint url-pattern='/webdav/*' role-name='webdav'/&gt;
</example>

<p>The following example is not recommended because it would allow anyone to
update the site:</p>

<example title="WebDAV with no security">
&lt;servlet&gt;
  &lt;servlet-name&gt;webdav&lt;/servlet-name&gt;
  &lt;servlet-class&gt;com.caucho.servlets.webdav.WebDavServlet&lt;/servlet-class&gt;
  &lt;init&gt;
    &lt;enable&gt;write&lt;/enable&gt;
    &lt;secure&gt;false&lt;/secure&gt;
    &lt;role&gt;*&lt;/role&gt;
  &lt;/init&gt;
&lt;/servlet&gt;

&lt;servlet-mapping url-pattern='/webdav/*' servlet-name='webdav'/&gt;
</example>

<p>The WebDAV servlet can point to a different directory by
setting the <var>root</var> parameter.  The path is relative to the
web-app, and allows path variables.  For example, the following would
read and write files from WEB-INF/webdav:</p>

<example title="WebDAV based on WEB-INF/webdav">
&lt;servlet&gt;
  &lt;servlet-name&gt;webdav&lt;/servlet-name&gt;
  &lt;servlet-class&gt;com.caucho.servlets.webdav.WebDavServlet&lt;/servlet-class&gt;
  &lt;init&gt;
    &lt;root&gt;WEB-INF/webdav&lt;/root&gt;
    &lt;enable&gt;write&lt;/enable&gt;
    &lt;role&gt;webdav&lt;/role&gt;
  &lt;/init&gt;
&lt;/servlet&gt;

&lt;servlet-mapping url-pattern='/webdav/*' servlet-name='webdav'/&gt;
</example>

<s2 title="Configuring Windows">

<p>Recent versions of Windows and the Windows Office suite directly
support WebDAV.  WebDAV is configured in "My Network Places".</p>

<p>When browsing "My Network Places" in IE, click on Tools/Map Network
Drive from the menu.  IE will open a dialog.  The dialog contains a
link to "Create a shortcut to Web folder or FTP site".  Clicking on
that will open the "Add Network Place Wizard".</p>

<p>The Add Network Place Wizard will ask for the location of the
WebDAV server.  Type the full URL, e.g. http://www.foo.com/webdav and
complete the dialog.</p>

<p>Adding the WebDAV link will let you save directly to your server.
Windows programs can load and save to the server.  You can also open an
IE window to the mapped folder and use it as a normal folder.</p>

</s2>

<s2 name="customize" title="Custom Path Sources">

<p>The WebDAV servlet can be customized to use a source other than the
default path source.  For example, it would be possible to use WebDAV
with files stored in a database.</p>

<p>There's a <code>&lt;path-source&gt;java:comp/env/my-path&lt;/path-source&gt;
</code> parameter in the WebDavServlet(see <a href="#configure">Configuring the
WebDAV Servlet</a>).  You configure an object with the JNDI name
<code>java:comp/env/my-path</code> using <a config-tag="resource"/> to
configure a custom class that extends <a href="javadoc|com.caucho.servlets.webdav.AbstractPath|"/></p>

<example title="WebDAV with a custom source">
&lt;resource jndi-name='resin/webdav'&gt;
  &lt;type&gt;test.foo.MyDataSource&lt;/type&gt;
  &lt;init&gt;
    &lt;my-foo&gt;bar&lt;/my-foo&gt;
  &lt;/init&gt;
&lt;/resource&gt;

&lt;servlet&gt;
  &lt;servlet-name&gt;webdav&lt;/servlet-name&gt;
  &lt;servlet-class&gt;com.caucho.servlets.webdav.WebDavServlet&lt;/servlet-class&gt;
  &lt;init&gt;
    &lt;enable&gt;write&lt;/enable&gt;
    &lt;path-source&gt;resin/webdav&lt;/path-source&gt;
  &lt;/init&gt;
&lt;/servlet&gt;

&lt;servlet-mapping url-pattern='/webdav/*' servlet-name='webdav'/&gt;
</example>

<p>You can completely customize your WebDav backend, 
linking it to databases or some EJB-based data source or whatever.</p>

</s2>

<s2 title="Configuring the WebDAV servlet to recognize more than one root folder?" type="faq">
 
<p>There's a "root" parameter for the WebDavServlet (see <a href="#configure">Configuring the WebDAV Servlet</a>).  You can
set that and use several separate webdav instances.</p>

<example>
&lt;servlet&gt;
  &lt;servlet-name&gt;webdav1&lt;/servlet-name&gt;
  &lt;servlet-class&gt;com.caucho.servlets.webdav.WebDavServlet&lt;/servlet-class&gt;
  &lt;init&gt;
    &lt;root&gt;/opt/root1&lt;/root&gt;
  &lt;/init&gt;
&lt;/servlet&gt;

&lt;servlet&gt;
  &lt;servlet-name&gt;webdav2&lt;/servlet-name&gt;
  &lt;servlet-class&gt;com.caucho.servlets.webdav.WebDavServlet&lt;/servlet-class&gt;
  &lt;init&gt;
    &lt;root&gt;/opt/root1&lt;/root&gt;
  &lt;/init&gt;
&lt;/servlet&gt;

&lt;servlet-mapping url-pattern='/root1' servlet-name='webdav1'/&gt;
&lt;servlet-mapping url-pattern='/root2' servlet-name='webdav2'/&gt;
</example>
</s2>

<s2 title="Making the root path match a user name?" type="faq">
<p>
What if one wants to make the root user-dependant? i.e. have user "ferg"
have the root in "/somefolder/ferg" and user "jeff" have the root in
"/somefolder/jeff"
</p>

<p>It's possible, but you need to write a bit of code.</p>

<p>As discussed in <a href="#customize">Custom Path Sources</a>, you
can customize the data source by creating your own ApplicationPath.</p>

<p>In this case, you probably want to extend 
<a href="javadoc|com.caucho.servlets.webdav.FilePath|"/> and override the 
getPath method.</p>

</s2>
</s1>

<s1 title="run-at">

<p>The "run-at" capability should now be configured using the
<a href="resources.xtp">&lt;scheduled-task></a> capability.</p>

</s1>

  </body>
</document>