<s1 title="Basic Configuration">

<p>Because the flexibility of Resin's configuration can be overwhelming, we've
collected the most important configuration here.  Once you understand the
basic configuration, you can use it as a framework to attach more detailed
configuration as you need it.</p>

<p>You may want to look at:</p>
<ul>
<li><a href="../java_tut/conf-basic.xtp">basic configuration</a> in the
tutorial section.
<li>System-specific <a href='starting.xtp'>installation</a> information is in
a different section.
<li>An <a href='config-index.xtp'>index</a> of all configuration elements.
</ul>

<s2 title='Configuration Overview'>

<p>Configuring Resin involves configuring the following:</p>

<ul>
<li>ports and protocols: <a href="http-config.xtp#http">http</a>, ssl, <a href="http-config.xtp#srun">srun</a>
<li>resources (<a href="jndi.xtp">JNDI</a>): <a href="db-config.xtp">databases</a>, <a href="jms.xtp">JMS</a>, EJB, JNDI links
<li>virtual hosts and web-applications
<li><a href="app-config.xtp#classpath">classpaths</a>
<li><a href="servlet.xtp">servlets</a>: web.xml
</ul>

<p>Resin organizes classes and JNDI resources into a tree.
Each node in the tree inherits classes and JNDI resources from
its parents and adds it's own classes and resources.  So a database
<var/jdbc/test/> configured for the <var/foo.com/> virtual host would
be available for every web-app in the host.</p>

<figure src="jndi_tree.gif"/>

</s2>

<s2 title='Complete resin.conf Example'>

<p>The following creates a basic working configuration for a Resin standalone
configuration.  Resin will compile and load servlets and classes placed
in <var//home/ferg/public_html/WEB-INF/classes/> and jars placed in
in <var//home/ferg/public_html/WEB-INF/lib/>.</p>

<p>The url <var//servlet/test.MyServlet/> will invoke a servlet in 
<var//home/ferg/public_html/WEB-INF/classes/test/MyServlet.class/>.</p>

<p>The url <var//hello.jsp/> will run a JSP in
<var//home/ferg/public_html/hello.jsp/>.</p>

<example title="Example resin.conf">
&lt;caucho.com>
&lt;http-server>

&lt;http port='8080'/>

&lt;host id=''>
  &lt;doc-dir>/home/ferg/public_html&lt;/doc-dir>

  &lt;war-dir>webapps&lt;/war-dir>

  &lt;web-app id='/'>
  &lt;/web-app>
&lt;/host>

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

<p>Servlet configuration normally belongs in the web.xml in the WEB-INF
directory.  Resin-specific configuration, e.g. database configuration,
belongs in a resin-web.xml file in WEB-INF or in the resin.conf.</p>

<p>Because Resin merges the contents of resin-web.xml, web.xml, and resin.conf,
so you can put everything in the resin.conf if that makes your application
easier to maintain.</p>

<p>The following web.xml configures the special "invoker" servlet, which lets
you call servlets using the classname in the URL like
/servlet/qa.MyServlet.  In general, it's a better idea to create specific
servlet-mappings for each servlet for better security.</p>

<example title="Example /WEB-INF/web.xml">
&lt;web-app>
  &lt;servlet-mapping>
    &lt;url-pattern>/servlet/*&lt;/url-pattern>
    &lt;servlet-name>invoker&lt;/servlet-name>
  &lt;/servlet-mapping>
&lt;/web-app>
</example>

</s2>

<objsummary/>

<s2 title='http configuration'>

<defun title='caucho.com'>
<p>caucho.com is just a container for any Caucho configuration</p>
</defun>

<defun title='http-server'>
<p><a href='http-config.xtp'>http-server</a> contains all
configuration for the Resin server.</p>

<p>The most important configuration variable is <var/app-dir/>.
<var/app-dir/> configures the document root.  <var/app-dir/> can appear
in <var/&lt;http-server>/>, <var/&lt;host>/>, and <var/&lt;web-app>/>.
If it's not specified, it defaults to the parent.</p>

<example title='Apache Config'>
&lt;caucho.com>
&lt;http-server>

&lt;app-dir>/usr/local/apache/htdocs&lt;/app-dir>

  ...

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

<example title='IIS Config'>
&lt;caucho.com>
&lt;http-server>

&lt;app-dir>d:\inetpub\wwwroot&lt;/app-dir>

  ...

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

<example title='Resin Config'>
&lt;caucho.com>
&lt;http-server>

&lt;app-dir>doc&lt;/app-dir>

  ...

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

<defun title='http'>
<p>Configures the HTTP port for Resin to listen at.</p>

<deftable>
<tr><th>Attribute<th>Meaning<td>Default
<tr><td>port<td>TCP post to listen to<td>required
<tr><td>host<td>TCP interface to listen to<td>all interfaces
</deftable>

<example>
&lt;caucho.com>
&lt;http-server>
  &lt;http host='localhost' port='6802'/>
  ...
&lt;/http-server>
&lt;/caucho.com>
</example>
</defun>

<defun title='srun'>
<p>Configures a servlet runner port for Resin to listen at.</p>

<deftable>
<tr><th>Attribute<th>Meaning<td>Default
<tr><td>port<td>TCP post to listen to<td>required
<tr><td>host<td>TCP interface to listen to<td>all interfaces
</deftable>

<example>
&lt;caucho.com>
&lt;http-server>
  &lt;srun host='localhost' port='6802'/>
  ...
&lt;/http-server>
&lt;/caucho.com>
</example>
</defun>

<defun title='host'>
<p>Each http-server contains some
<a href='virtual-host.xtp'>virtual hosts</a>.  Most
configurations will use the default host.</p>

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

&lt;host id=''>
  ...
&lt;/host>

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

<defun title='web-app'>
<p>Each host contains some <a href='app-config.xtp'>web
applications.</a>  A web application is just a container for
some servlets.  It's closely related to the
javax.servlet.ServletContext.
Most configurations will use the default web-app.</p>

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

&lt;host id=''>
&lt;web-app id='/'>

...

&lt;/web-app>

&lt;/host>

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

</s2>

<s2 title='Servlets'>

<defun title='servlet-mapping'>
<p>Maps url patterns to servlets.  <code/servlet-mapping/> has two
children, <var/url-pattern/> and <code/servlet-name/>.
<var/url-pattern/> selects the urls which should execute the servlet.</p>

<p>The special <code/servlet-name/> <em/invoker/> is used to dispatch
servlets by class name.  For example, /servlets/test.HelloServlet.

<deftable title='url-patterns'>
<tr><td>/path/to/servlet<td>Exact URL match
<tr><td>/prefix/*<td>Matching everything with a prefix
<tr><td>*.jsp<td>Matching everything with an extension
<tr><td>/<td>Replace the default servlet
</deftable>

<p>In the following example, the URL <var//hello-world/> invokes the servlet
</p>

<example>
&lt;web-app id='/'>

&lt;servlet>
  &lt;servlet-name>hello&lt;/servlet-name>
  &lt;servlet-class>test.HelloWorld&lt;/servlet-class>
&lt;/servlet>

&lt;servlet-mapping>
  &lt;url-pattern>/hello-world&lt;/url-pattern>
  &lt;servlet-name>hello&lt;/servlet-name>
&lt;/servlet-mapping>

&lt;servlet-mapping>
  &lt;url-pattern>*.xtp&lt;/url-pattern>
  &lt;servlet-name>com.caucho.jsp.XtpServlet&lt;/servlet-name>
&lt;/servlet-mapping>

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

<defun title='servlet'>
<p>Defines a servlet alias for later mapping.  More details are in the
<a href='servlet-config.xtp'>servlet configuration</a> section.</p>

<deftable>
<tr><td>servlet-name<td>The servlet's name (alias)
<tr><td>servlet-class<td>The servlet's class (defaults to servlet-name)
<tr><td>init-param<td>Initialization parameters
</deftable>

<p>In the following example, the url <var//hello.xtp/> invokes the
servlet <var/test.HelloWorld/>.  The servlet will use getInitParameter("title") to get the string "Hello, World".</p>

<example>
&lt;web-app id='/'&gt;

&lt;servlet-mapping>
  &lt;url-pattern>/hello.xtp&lt;/url-pattern>
  &lt;servlet-name>hello&lt;/servlet-name>
&lt;/servlet-mapping>

&lt;servlet>
  &lt;servlet-name>hello&lt;/servlet-name>
  &lt;servlet-class>test.HelloWorld&lt;/servlet-class>
  &lt;init-param title='Hello, World'/&gt;
&lt;/servlet&gt;

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

</s2>

<s2 title='Formal Description'>

<p>The following description condenses the full
<a href='config-sum.xtp'>configuration summary</a>.</p>

<def>
caucho.com ::= <a href='http-config.xtp#http-server'>http-server</a>&nbsp;

<a href='http-config.xtp'>http-server</a> ::= <a href='http-config.xtp#http'>http</a>* |
                <a href='http-config.xtp#srun'>srun</a>* |
                <a href='http-config.xtp#host'>host</a>*

<a href='http-config.xtp#host'>host</a> ::= <a href='http-config.xtp#war-dir'>war-dir</a> |
         <a href='app-config.xtp#web-app'>web-app</a>*

<a href='app-config.xtp#web-app'>web-app</a> ::= <a href='app-config.xtp#servlet-mapping'>servlet-mapping</a>* |
            <a href='app-config.xtp#servlet'>servlet</a>*

<a href='servlet-config.xtp#servlet'>servlet</a> ::= <a href='servlet-config.xtp#servlet-name'>servlet-name</a> |
            <a href='servlet-config.xtp#servlet-class'>servlet-class</a> |
            <a href='servlet-config.xtp#init-param'>init-param</a>*

<a href='app-config.xtp#servlet-mapping'>servlet-mapping</a> ::= <a href='app-config.xtp#url-pattern'>url-pattern</a> |
                    <a href='servlet-config.xtp#servlet-name'>servlet-name</a>

</def>

</s2>
</s1>