<title>Servlet Configuration</title><p/>Resin configuration is based on the <var/resin.conf/> file locatedin <var/resin1.2.x/conf/resin.conf/>.  It's XML-based, although itallows for some non-XML laziness like omitting quotes from attributes.<p/>The application configuration is based on the Servlet 2.2deployment descriptor.<p/>The configuration file parses into a (key, value) structure.  LISPfans will recognize it as similar to an A-list and Windows fans willrecognize it as similar to the NT registry.  Unlike either, though,multiple items with the same key are allowed.<p/><note>Because the internal format has less structure than XML does,you can use either an element-based configuration or anequivalent attribute-based configuration.  You should use whicheverconfiguration simplifies your maintenance.  The following example usesthe element-based configuration exclusively.</note><example title="resin.conf">&lt;caucho.com>&lt;http-server app-dir='doc'>  &lt;http port='8080'/>  &lt;host id=''>    &lt;web-app id='/test'/>  &lt;/host>&lt;/http-server>&lt;/caucho.com></example><example title="web.xml">&lt;web-app>  &lt;servlet servlet-name='hello'           servlet-class='test.HelloServlet'>    &lt;init-param greeting='Hello, world'/>  &lt;/servlet>  &lt;servlet-mapping url-pattern='/hello'                   servlet-name='hello'/>  &lt;servlet-mapping url-pattern='/prefix/*'                   servlet-name='hello'/>  &lt;servlet-mapping url-pattern='*.hello'                   servlet-name='hello'/>&lt;/web-app></example><subsection>  <title><a href="../ref/resin-config.xtp">caucho.com</a></title>The Resin configuration file is based on XML.  The<var/&lt;caucho.com>/> element encapsulates the entireconfiguration file.</subsection><subsection>  <title><a href="../ref/resin-config.xtp#http-server">http-server</a></title>Each resin.conf contains a single <var/&lt;http-server>/> element thatcontains the configuration for the web server and servlet engine.  Allconfiguration outside the <var/http-server/> is non-server specific.For example, debug logging configuration and Java compilerconfiguration belongs outside the <var/http-server/> element.<p/>Despite its name, <var/http-server/> contains configuration forthe standalone HTTP server and the servlet runner.  In fact, you canlisten to multiple HTTP and servlet runner ports in the name<var/http-server/>.<p/>In the current version of Resin only allows a single <var/http-server/>.</subsection><subsection>  <title><a href="../ref/app-config.xtp#app-dir">app-dir</a></title><var/app-dir/> configures the application directory, which containsthe documents, the servlets, the bean classes, and some extraconfiguration files like web.xml and taglib.tld.  For many, theapp-dir is the most important configuration.  For example, if you'reusing Apache or IIS, you'll change app-dir to point to the Apachehtdocs or the IIS inetpub/wwwroot.<p/><var/app-dir/> can be used in the http-server, as above, in the host andin the web-app.  If unspecified, it defaults to the directory of theenclosing block.<p/>The sample resin.conf in the distribution points to anapp-dir <var/doc/>.  If you start Resin from the distribution, you canput a hello.jsp in <var/resin1.2.x/doc/hello.jsp/> and you'll view itfrom a browser using <var/http://localhost:8080/hello.jsp/>.<p/>Application servlets and classes belong in <var/WEB-INF/classes/> and jarsbelong in <var/WEB-INF/lib/>.  Resin will automatically reload a classplaced in either location.  External jars, for example a databasedriver, should be put in <var/resin1.2.x/lib/> instead.<p/>The <var/WEB-INF/> directory is hidden by the web server.  So, itis not possible for a browser to look at anything in that directory.<p/><b>Note: JNI</b>.  Because of the way Java handles JNI, you shouldplace the Java <var/native/> classes outside the <var/WEB-INF/>directories, putting them in <var/resin1.2.x/lib/> or<var/resin1.2.x/classes/> instead.  That means you'll need to restartResin when you change those classes, so you should only put theinterface classes outside WEB-INF.</subsection><subsection>  <title><a href="../ref/http-config.xtp#http">http</a></title>In Resin 1.2, you must specify each port and protocol for the webserver.  In the example, Resin will listen to port 8080 using theHTTP protocol.  Earlier versions of Resin would listen to port 8080 bydefault.<p/>Configurations using Resin as a servlet runner for another webserver will use an <a href="../ref/http-config.xtp#srun">srun</a> tagto listen for the servlet runner.<p/>Resin 1.2 allows multiple <var/http/> and <var/srun/> tags.  Avirtual host configuration might use separate <var/http/> tags foreach IP interface on the server.  A load balancing configuration willuse several <var/srun/> tags, each representing a different backendserver, and selected by the <a href="../ref/http-config.xtp#srun">id</a> attribute.</subsection><subsection>  <title><a href="../ref/http-config.xtp#host">host</a></title>The <var/host/> element contains configuration for a virtual host.The virtual host with <var/id=''/> is the default virtual host.  IfResin doesn't match any other host, it will use the configuration inthe default virtual host.  This example and most configurations willuse the default virtual host.<p/>To configure a virtual host, just copy the default <var/host/>block and set the <var/id/> attribute to the host name.  You'llprobably want to set the <ahref="../ref/app-config.xtp#app-dir">app-dir</a>for the new virtual hostso it will use a different application directory than the default host.</subsection><subsection>  <title><a href="../ref/http-config.xtp#web-app">web-app</a></title><var/web-app/> (web application) is the core of Resin's jsp andservlet configuration.  Each application has its own class loader,ServletContext variable, and <var/WEB-INF/> directory.web-app uses the same syntax as the servlet 2.2deployment descriptor with a few optional extensions.<p/>The web-app with <var/id='/'/> is the default web application.It's a good idea not to go overboard in creating web-apps.  Mostsites should just use the single default.  Each web-app has itsown <a href="../ref/app-config.xtp#app-dir">app-dir</a>.  Ifunspecified, as in the example, it defaults to the <var/id/> pathbelow the host's app-dir.  A web-app <var/id='foo'/> startsin <var/resin1.2.x/doc/foo/> and the WEB-INF willbe <var/resin1.2.x/doc/foo/WEB-INF/>.</subsection><subsection>  <title><a href="../ref/servlet-config.xtp#servlet">servlet</a></title><p/>Servlet configuration follows the Servlet 2.2 deploymentdescriptor configuration.  The<a href="../ref/servlet-config.xtp#servlet">servlet</a> tag assigns a name to a servlet and specifies its class.  Servlets which needconfiguration will use<a href="../ref/servlet-config.xtp#servlet">init-param</a> to configureservlet parameters.<p/>To actually use a servlet, you'll need to add a<a href="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a> tagfor each servlet.<p/>Each <var/servlet/> tag specifies a separate servlet instance.You can create several servlet instances, each with different initparameters and different names, by creating multiple <var/servlet/>tags.<p/>Servlets and their supporting classes generallybelong in <var/WEB-INF/classes/> or in a jar in <var/WEB-INF/lib/>.A servlet class <var/test.Hello/> would belong in<var/WEB-INF/classes/test/Hello.class/>.Resin will automatically reload the servlets whenthey change.  You can put servlets and their classes in the systemclasspath, for example, <var/resin1.2.x/lib/>, but they will not bereloaded automatically.</subsection><subsection>  <title><ahref="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a></title><p/><var/servlet-mapping/> specifies the URLs that invoke a servlet.The longest match between the URL and all the <var/servlet-mapping/>entries will select the servlet.  If none of the<var/servlet-mapping/> entries match, Resin will serve the URL as astatic file.<p/>With a web-server like Apache, the servlet-mapping entriesdetermine which URLs belong to Resin and which belong to Apache.  Anymatch belongs to Resin and a non-match will belong to Apache.  You canuse the special <var/caucho-status/> URL to look at the mapping.<p/>The <a href="../ref/app-config.xtp#url-pattern">url-pattern</a>specifies the URLs to match.  The four patterns in the Servletspecification are <var/*.foo/>, <var//specific/>, <var//prefix/*/>,and <var///>.<p/>The <var/servlet-name/> in the <var/servlet-mapping/> matches a<var/servlet-name/> in a <var/servlet/>.  As a Resin extension, youcan specify all the <var/servlet/> configuration in the<var/servlet-mapping/> itself, avoiding the double entry.</subsection>