<title>Caucho Servlet Engine on Netscape Unix</title>

<summarylist/>

Resin provides a fast servlet runner for Netscape, allowing Netscape
to run servlets, JSP and XTP files.

<p/>To configure Resin with Netscape, you must follow the following steps:
<ol>
<li>Compile caucho_nsapi.so
<li>Configure Netscape
<li>Configure resin.conf
<li>Restart Netscape and start srun
</ol>

<section title='Compiling caucho_nsapi.so'>

To compile and install <var/caucho_nsapi/> on Unix, you'll need to run
<code/configure/> and then make.

<p/>The argument to --with-netscape is the directory containing the netscape
start and stop scripts, i.e. the parent of the config directory.

<def>
unix> ./configure --with-netscape=/usr/local/netscape/https-your-hostname
unix> make
</def>

<p/>If you need finer control over the Netscape configuration, you can use
the following arguments to ./configure.  Resin needs
<var/netscape-include/> and <var/netscape-conf/>.

<deftable>
<tr><td>--with-netscape=dir<td>The Netscape root directory.
<tr><td>--with-netscape-include=dir<td>The Netscape include directory.
<tr><td>--with-netscape-conf=conf<td>The Netscape obj.conf file
</deftable>

</section>

<section title='Configuring Netscape by hand'>

<p/>Making caucho_nsapi will automatically change your obj.conf file.
For reference, here are the changes:

<example title=obj.conf>
Init fn="load-modules" shlib="&lt;build-dir>/caucho_nsapi.so" \
   funcs="caucho_service,caucho_filter,caucho_status"

&lt;Object name=default>
NameTrans fn="caucho_filter" conf="&lt;resin-home>/resin.conf" name="resin"
NameTrans fn="assign-name" from="/caucho-status" name="caucho-status"
...
&lt;/Object>

&lt;Object name="resin">
Service fn="caucho_service"
&lt;/Object>
&lt;Object name="caucho-status">
Service fn="caucho_status"
&lt;/Object>

</example>

<note>The caucho-status is optional and probably should be avoided in
a production site.  It lets you ask plugin module about the
Caucho status, valuable for debugging.</note>

<p/>Restart Netscape.  Now browse http://localhost/caucho-status.  It
should return a table indicating that the servlet runner is stopped.

<p/>Browse http://localhost/test.jsp.  It should return a message like:
<results>
Cannot connect to Servlet Runner.
</results>

<a name='balance'/>
<subsection title='Load Balancing' version='Resin 1.2'>

In Resin 1.2, you can distribute requests to multiple machines.  All
requests in a session will go to the same host.  In addition, if one
host goes down, Resin will send the request to the next available machine.

<p/>In addition, you can specify backup machines.  The backup only will serve
requests if all primaries are down.

<p/>See the <a href='http-config.xtp'>http config</a> section for more
details.
<example title=resin.conf>
&lt;caucho.com>
&lt;http-server>
  &lt;srun id="a"host='host1' port='6802'/>
  &lt;srun id="b" host='host2' port='6802'/>
  &lt;srun-backup id="c" host='backup port='6802'/>
  ...
&lt;/http-server>
&lt;/caucho.com>
</example>
</subsection>
</section>

<section title='Configuring resin.conf'>

By default, Resin will look in resin1.2/doc for JSP files and
resin1.2/doc/WEB-INF/classes for servlets and beans.  To tell Resin
to use Netscapex's document area, you configure the <var/app-dir/>.
Change <var/app-dir/> from 'doc' to something like '/usr/local/netscape/doc'.

<example title='resin.conf'>
&lt;caucho.com>
  &lt;http-server
      app-dir='/usr/local/netscape/docs'>
    &lt;servlet-mapping url-pattern='/servlets/*'
              servlet-name='invoker'/>

    &lt;servlet-mapping url-pattern='*.xtp'
                        servlet-name='com.caucho.jsp.XtpServlet'/>
    &lt;servlet-mapping url-pattern='*.jsp'
                        servlet-name='com.caucho.jsp.JspServlet'/>
  &lt;/http-server>
&lt;/caucho.com>
</example>

</section>

<section title="Netscape's obj.conf">

Installing Resin with Netscape modifies Netscape's obj.conf file.  For most
users, the default installation will be fine.  More sophisticated users
will need to modify the obj.conf file.

<example>
Init fn=load-types mime-types=mime.types
# load resin shared library
Init fn="load-modules" shlib="/home/resin/libexec/caucho_nsapi.so" \
     funcs="caucho_service,caucho_filter,caucho_status"

&lt;Object name=default>
# you can change the conf value
NameTrans fn="caucho_filter" conf="/home/resin/conf/resin.conf" name="resin"
# comment out the following in production sites
NameTrans fn="assign-name" from="/caucho-status" name="caucho-status"
NameTrans fn=pfx2dir from=/ns-icons dir="/usr/local/src/nes/ns-icons" name="es-internal"
NameTrans fn=pfx2dir from=/mc-icons dir="/usr/local/src/nes/ns-icons" name="es-internal"

...
&lt;/Object>

...

&lt;Object name="resin">
Service fn="caucho_service"
&lt;/Object>

&lt;Object name="caucho-status">
Service fn="caucho_status"
&lt;/Object>
</example>
</section>

<section title='Testing the servlet engine'>

Now you need to start the servlet engine.

<example>
> resin2.0/bin/httpd.sh
</example>

<p/>Now browse http://localhost/test.jsp.  You should get a 'file not
found' message.

<p/>Create a test file '/usr/local/netscape/htdocs/test.jsp'

<example>
2 + 2 = &lt;%= 2 + 2 %>
</example>

<p/>Browse http://localhost/test.jsp again.  You should now get

<results>
2 + 2 = 4
</results>

</section>

<section title='Servlet Engine Production'>

A better way to run the servlet engine in a production environment is
to use the start and stop scripts.  These scripts add extra
reliability to the server.  If Resin should ever exit, it will
automatically be restarted.

<p/>To start the servlet runner, use

<example>
unix> resin2.0/bin/httpd.sh start
</example>

<p/>To stop it, use

<example>
unix> resin2.0/bin/httpd.sh stop
</example>

</section>

<section title='Windows'>

On Windows, the setup program should configure the obj.conf.  Except that
you don't need to compile the plugin on windows, the configuration is
identical.

</section>
