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

ErrorStatusServlet

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

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.

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

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.

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

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

#!/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.

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

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

<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 com.caucho.servlets.FastCGIServlet.

HttpProxyServlet

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

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

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

SSIServlet

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 Apache httpd.

<web-app xmlns="http://caucho.com/ns/resin">
  <servlet-mapping url-pattern="*.shtml"
                   servlet-class="com.caucho.servlets.ssi.SSIServlet"/>
</web-app>

<h1>A little test</h1>

<!--#config timefmt="%Y-%m-%d" -->
<!--#echo var="DATE_GMT" -->

<!--#include virtual="inc.jsp" -->

<!--#set var="a" value="$REQUEST_METHOD" -->
<!--#include virtual="inc.jsp?q=$a" -->