<title>Troubleshooting</title>

<summarylist/>
<subsection title='JSP uses the wrong JDK version'>

On Win32, Resin tries to find Java in the following
order:

<ul>
<li>The command-line argument, -java_home
<li>The environment variable JAVA_HOME
<li>The registry, using JavaSoft's CurrentVersion of the JDK.
<li>Following the PATH of the java executable.
</ul>

To find out which Java version Caucho JSP is using, use the
'-version' argument on the command line:

<def>
resin1.1> bin/httpd -version
</def>

</subsection>

<subsection title="Apache won't start on Win32">

The error message might be something like:

<example>
"Syntax error on line 785 of
C:\PROGRA~1\APACHE~1\APACHE/conf/httpd.conf:
Cannot load c:\resin1.1\srun\win32-1.3.6\mod_caucho.dll into server:"
</example>

This will happen if the dll is incompatible with the Apache version.
Send us a message and we'll make sure you get the right compiled version.

</subsection>

<subsection title="srun/install.sh won't compile with Apache 1.3.9">

This appears to be a problem with Apache for some versions of Unix.
Apache's apxs script is missing loader commands.  You'll have to
modify the apxs script (in /usr/local/apache/bin/apxs) to look
something like:

<example>
my $CFG_CFLAGS_SHLIB  = '-fpic -DSHARED_MODULE';
my $CFG_LD_SHLIB      = 'ld';
my $CFG_LDFLAGS_SHLIB = '-Bshareable';
</example>

</subsection>

<subsection title='Apache/IIS cannot contact to servlet runner'>

The particular error message is something like:

<def>
Cannot connect to servlet runner at localhost:6802
</def>

<p/>The servlet runner process needs to be started.  In resin1.1/bin
the srun executable will start the servlet runner.

<p/>The srun executable will start Java and wait for connections from the
web server.

</subsection>

<subsection title='File not found'>

The web server (IIS or Apache) and the servlet runner (srun), need to find the
web pages.  The resin.conf file configures srun.  You need to add a
'app-dir' property, to tell srun where to look for the root directory.

<example>
&lt;caucho.com>
  &lt;http-server app-dir='d:\InetPub\wwwroot'>
    &lt;servlet-mapping url-pattern='*.jsp'
      servlet-name='com.caucho.jsp.JspServlet'>
  &lt;/http-server>
&lt;/caucho.com>
</example>

</subsection>

<subsection title='browser returns test.jsp source'>

If you're running Resin with IIS or Apache, the web server might not
know how to handle *.jsp files.  On Apache, the httpd.conf needs to
add Resin.  On IIS, the IIS configuration needs to dispatch *.jsp
files to srun_iis.dll.

<p/>Both may need restarting to see the changes.

<p/>To test if this is the problem, stop the srun executable.  If you
browse http://localhost/test.jsp, you should get the 'Cannot connect
to servlet runner' message.

</subsection>

<subsection title='How to get debugging information'>

Resin can write debugging information to standard output or to any
file.  To add debugging information add a <var/log/> directive to the
resin.conf file.

<example>
&lt;caucho.com>
  &lt;log id='/' href='stderr:'/>
&lt;/caucho.com>
</example>

<var/href/> can be any path.  stderr: is perhaps the most useful.
<var/id/> can select which portions of Resin to get logging
information.  Here are some useful patterns:

<deftable>
<tr><td>/<td>Debug everything
<tr><td>/caucho.com/jsp<td>Debug jsp
<tr><td>/caucho.com/jsp/java<td>See the JSP generated Java
<tr><td>/caucho.com/jsp/js<td>See the JSP generated Java
<tr><td>/caucho.com/xsl<td>XSL debugging
<tr><td>/caucho.com/tcp-server
    <td>See thread creation and deletion
<tr><td>/caucho.com/http
    <td>HTTP related information
</deftable>

</subsection>

<subsection title="Resin doesn't update changed servlets and JSP pages">

Resin has a delay for testing updated servlets and JSP pages.
The configuration variable for both is 'class-update-interval' in
resin.conf.  It's an application-level variable.  The default is 15
seconds.  So Resin will only check every 15 seconds for an updated
page.  You can set this value to 0 for development work.

<example>
&lt;http-config class-update-interval='0'>
  ...
&lt;/http-config>
</example>

<p/>If you want Resin to check servlets for updates every hour, your
resin.conf might look like:

<example>
&lt;http-config class-update-interval='3600'>
  ...
&lt;/http-config>
</example>

</subsection>

<subsection title="Java JSP doesn't compile">

<boundary-box>
java.lang.NoClassDefFoundError: sun/tools/javac/Main
</boundary-box>

<p/>The JRE does not contain a Java compiler.  You either need to get
the JDK or use another compiler.  To configure another compiler use:

<example>
&lt;caucho.com>
  &lt;java compiler='/usr/local/bin/jikes'/>
  ...
&lt;/caucho.com>
</example>

</subsection>

<subsection title="How do I get exception line numbers?">

For debugging, it is crucial to get proper line numbers.
Unfortunately, Java JITs (just-in-time compilers) remove the line
numbers.

<p/>For development we recomment you turn jit compiling off.  On unix,
start the server as:

<example>
unix> httpd.sh -nojit
</example>

</subsection>

<subsection title="How do I enable session url rewriting?">

<p/>This is only supported in Resin 1.1.b1 and later.  You can disable
cookies in the resin.conf with a configuration like

<example>
&lt;http-server&gt;

  &lt;session-config
   enable-cookies='false'
   enable-url-rewriting='true'/&gt;

&lt;/http-server&gt;
</example>

</subsection>

<subsection title="How do I keep the generated .java files?">

<p/>By default, Resin removes the generated .java files from a .jsp.
To keep the files, you need to add a special logging statement.
(Don't worry, it won't generate any output.)

<example>
&lt;caucho.com&gt;
  &lt;log id='/caucho.com/jsp/source' href='stderr:'/&gt;

  &lt;http-server&gt;
    ...
  &lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

</subsection>

<subsection title="How do I use multiple resin.conf files?">

<p/>This is especially important if you want to use a different
workspace for development than deployment.  Just call the
<code/httpd/> or <code/srun/> executable with the -conf flag.

<example>
unix> httpd.sh start -conf devel.conf -verbose
</example>

<example>
d:\> httpd.exe -conf devel.conf -verbose
</example>

</subsection>
