<title>Basic Configuration</title>

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/>You may want to look at
<a href="../java_tut/conf-basic.xtp">basic configuration</a> in the
tutorial section.

<p>System-specific <a href='starting.xtp'>installation</a> information is in
a different section.

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

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>The url <var//servlet/test.MyServlet/> will invoke a servlet in 
<var//home/ferg/public_html/WEB-INF/classes/test/MyServlet.class/>.

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

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

&lt;http port='8080'/>

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

  &lt;web-app id='/'>
    &lt;servlet-mapping>
      &lt;url-pattern>/servlet/*&lt;/url-pattern>
      &lt;servlet-name>invoker&lt;/servlet-name>
    &lt;/servlet-mapping>

    &lt;servlet>
      &lt;servlet-name>jsp&lt;/servlet-name>
      &lt;servlet-class>com.caucho.jsp.JspServlet&lt;/servlet-class>
    &lt;/servlet>

    &lt;servlet-mapping>
      &lt;url-pattern>*.jsp&lt;/url-pattern>
      &lt;servlet-name>jsp&lt;/servlet-name>
    &lt;/servlet-mapping>
  &lt;/web-app>
&lt;/host>

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

</section>

<section title='Semi-Formal Description'>

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

<code><pre>
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#web-app'>app-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>

</pre></code>

</section>

<objsummary/>

<section name='http configuration' title=http>

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

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

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

<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'>
<sum>Configures the HTTP port for Resin to listen at.</sum>

<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'>
<sum>Configures a servlet runner port for Resin to listen at.</sum>

<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'>
<sum>Each http-server contains some
<a href='virtual-host.xtp'>virtual hosts</a>.</sum>  Most
configurations will use the default host.

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

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

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

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

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

</section>

<section name='Servlets' title=servlets>

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

<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

<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 name=servlet title='servlet' index='servlet'>
<sum>Defines a servlet alias for later mapping.</sum>  More details are in the
<a href='servlet-config.xtp'>servlet configuration</a> section.

<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 <a href='../javadoc/javax/servlet/ServletConfig.html#getInitParameter(java.lang.String)'>getInitParameter("title")</a> to get the string "Hello, World".

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

</section>
