Servlet Library
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Quercus
Servlets and Filters
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

Servlets
Servlet Lib
run-at
Filters
Filter Lib
Tutorials
FAQ

WebDAV
Servlets
Servlets and Filters
WebDAV

Resin provides a set of convenient servlets in the com.caucho.servlets.* package.

  1. ErrorStatusServlet
  2. LoadBalanceServlet
  3. CGIServlet
  4. DirectoryServlet
  5. FastCGIServlet
  6. HttpProxyServlet

ErrorStatusServlet

Sends an HTTP error code and optionally an error message back to the client.

ParameterMeaningdefault
status-codethe HTTP status code to send404
messagethe message to sendno message

This servlet is particularily useful for blocking access to portions of your web-app that contain files not meant to be accessible to users. In this example, the default 404 (meaning "Not Found") is used as the error message; the user cannot even determine if the file they are trying to access exists.

Blocking access to files using the ErrorStatusServlet
<web-app>
  <servlet>
    <servlet-name>block-access</servlet-name>
    <servlet-class>com.caucho.servlets.ErrorStatusServlet</servlet-class>
  <servlet>

  <servlet-mapping>
    <servlet-name>block-access</servlet-name>
    <url-pattern>/config/*</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>block-access</servlet-name>
    <url-pattern>*.properties</url-pattern>
  </servlet-mapping>

  ...

</web-app>
See class com.caucho.servlets.ErrorStatusServlet .

LoadBalanceServlet

Configures a front-end Resin instance to load-balance requests to backend Resin instances. Each LoadBalanceServlet instance will distribute the requests to a configured cluster.

The urls that get load balanced are the ones that are mapped to the LoadBalancedServlet, using the usual servlet-mapping.

LoadBalanceServlet supports sticky-sessions. If the request already has a session, the backend server matching that session will be used. Otherwise, the least busy backend server will be used as counted by number of active requests. If several backend servers are equally busy, the selection uses a round-robin to distribute the load.

ParameterMeaningdefault
cluster-idthe cluster that gets the matching requestsrequired
sticky-sessionswhether or not sessions should be stickytrue
strategythe load balancing strategy, `round-robin' or `least-connection'least-connection

The usual case balances all requests to backend servers. The front-end Resin instance has a resin.conf 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.conf file that configures the web site, similar to a conf file that is used when only one instance of Resin used for the server.

frontend.conf
<resin xmlns="http://caucho.com/ns/resin">
  <server>

    <http id='frontend' port='8080'/>

    <cluster id='backend'>
      <srun id='a' host='192.168.0.11' port='6810'/>
      <srun id='b' host='192.168.0.12' port='6810'/>
    </cluster>

    <!-- the front-end does the access logging -->
    <access-log path='log/access.log'>
      <rollover-period>2W</rollover-period>
    </access-log>

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

        <servlet-mapping url-pattern='/*' servlet-name='backend'/>
      </web-app>
   </host>
  </server>
</resin>

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

The strategy 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.

See class com.caucho.servlets.LoadBalanceServlet .

CGIServlet

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

ParameterMeaningdefault
executablePath to the script programdefault exec

<web-app>
  <servlet>
    <servlet-name>cgi</servlet-name>
    <servlet-class>com.caucho.servlets.CGIServlet</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>cgi</servlet-name>
    <url-pattern>*.cgi</url-pattern>
  </servlet-mapping>
</web-app>

See class com.caucho.servlets.CGIServlet

.

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 Content-Type: header and then a blank line before the content:

Minimal CGI script
#!/bin/sh

echo "Content-Type: text/html"
echo
echo "<h>CGI Test<h1>"
echo "CGI Test"

echo "<pre>"
env
echo "</pre>"

DirectoryServlet

The directory servlet provides the basic directory browsing. Sites will normally disable it.

ParameterMeaningdefault
enableEnable or disable the servlettrue

<servlet servlet-name="directory"
         servlet-class="com.caucho.servlets.DirectoryServlet">
  <init enable="false"/>
</servlet>

FastCGIServlet

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

ParameterMeaningdefault
server-addressthe host and port number, in the form host:portrequired

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

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

WEB-INF/web.xml
<web-app>
  <servlet>
    <servlet-name>php-fastcgi</servlet-name>
    <servlet-class>com.caucho.servlets.FastCGIServlet</servlet-class>
    <init>
      <server-address>localhost:6666</server-address>
    </init>
  </servlet>
  <servlet-mapping>
    <servlet-name>php-fastcgi</servlet-name>
    <url-pattern>*.php</url-pattern>
  </servlet-mapping>
</web-app>

Assuming PHP has been compiled with -fastcgi enabled, you might start PHP like:

unix> php -b 6666 

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

resin.conf
<web-app-default>
  <servlet>
    <servlet-name>php-fastcgi</servlet-name>
    <servlet-class>com.caucho.servlets.FastCGIServlet</servlet-class>
    <init>
      <server-address>localhost:6666</server-address>
    </init>
  </servlet>

  <servlet-mapping url-pattern="*.php"   servlet-name="php-fastcgi"/>
  <servlet-mapping url-pattern="*.phtml" servlet-name="php-fastcgi"/>

</web-app>
See class com.caucho.servlets.FastCGIServlet .

HttpProxyServlet

class com.caucho.servlets.HttpProxyServlet is a servlet that proxies to another server. This can be useful for providing access to legacy backend servers.

HttpProxyServlet
  <servlet>
    <servlet-name>http-proxy</servlet-name>
    <servlet-class>com.caucho.servlets.HttpProxyServlet</servlet-class>
    <init host='localhost:8081'/>
  </servlet>

  <servlet-mapping url-pattern="/foo/*" servlet-name="http-proxy"/>
  <servlet-mapping url-pattern="/bar/*" servlet-name="http-proxy"/>

There is a bit more power using servlet-regexp and regular expressions:

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


Servlets
Servlets and Filters
WebDAV
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.