Tag Definitions

If you've read all the pages in this book up to this chapter, you have gained quite a bit of experience with the Resin configuration file found in the installation's /conf directory. However, we have only scratched the surface of the available options. In this chapter, our goal is to present the entire Resin configuration file, the possible settings, and how they affect the execution of the server and supported applications. In areas such as databases and logging, we will point you to the appropriate chapters where the information is covered.

Details of resin.conf

The Resin configuration file is commonly found in the /conf directory of the installation path. By default, the filename is resin.conf. If you need to use a different configuration file (such as in a development situation), you can tell the server about the new file using the -conf <filename> command-line option. For example:

 httpd.exe —conf c:\resinconfs\dev.conf 

When you open the configuration file, all the information is provided as XML elements, attributes, and associated values.

XML Elements

You can add comments to the configuration file using the <!--> combination:

 <!-- this is a comment --> Comments can also span multiple rows <!-- this is a comment     - on multiple lines --> 

The XML in the configuration file can be used in both canonical and attribute formats. Consider the following XML element layout:

 <root>      <sub> value </sub> </root> 

The same information can be converted to use attributes and represent the same hierarchy and data:

 <root sub='value' /> 

Environments

The Resin configuration incorporates the concept of an environment. Environments are allowed to incorporate element tags that relate to resources or properties which might change from host to host or Web application to Web application. Some of the high-level information that can be incorporated in an environment includes:

• Classloaders

• Resources

• Logs

• Properties

• JNDI

• Other miscellanous tags

In this chapter we discuss a variety of tags, pointing out which ones can appear in environments and which ones cannot. The environments are defined within the <resin>, <server>, <host-default>, <host> and <web-app-default>, and <web-app> elements. When there are multiple environments, an inner environment will inherit the parent elements.

High-Level Configuration Format

To give you a feel for the amount of configuration information that can be stored in the Resin configuration file, Listing 15.1 shows the high-level elements under the root element. Of particular note is the <web-app> element hierarchy. All the information in this element can be placed in the web.xml files found in each Web application's WEB-INF directory. Only the high-level <web-app> with the ID attributes needs to be in the Resin configuration file.

Listing 15.1: Resin configuration high-level hierarchy.

           <resin xmlns="http://caucho.com/us/resin">             <databaae>             </database>             <server>               <host-default>               </host-default>               <resin:include path="app-default.xml"/>               <host>                 <web-app>                 </web-app>               </host>             </server>           </resin> 

Using #include and app-default.xml

If you look at any of the Resin configuration files, you will see that they can be large and cumbersome. The developer or system administrator has the option of breaking apart the configuration file into smaller chunks by using the resin:include statement. The <resin:include> tag will automatically pull in the contents of the provided file name and place them where the tag is located. Looking at Listing 15.1, you will see a <resin:include> tag has been used to pull in a file called app-default.xml.

The app-default.xml file is usually placed in the same directory as resin.conf. The file contains an environment for all Web applications hosted by Resin. The idea behind the file is to place default information that all Web applications will be able to use without defining their own tags. If a Web application needs to override a tag value, it just places a duplicate in its <web-app> element. Since Resin works in environments, the <web-app> environment will override the default environment.

Default Path Values

Throughout the configuration file are attributes for defining an id or href path. The value for the href/id can be an absolute path or a relative one. Resin also defines a number of global variables that you can use in the path definition. In addition to the following variables, the paths can contain JSP-EL expressions:

• $resin_home— The default installation directory of the Resin server.

• $server-root— The root of the server instance.

• $host-root— When used with the <host> element, contains the application directory.

• $app-dir— When used with the <web-app> element, contains the application directory.

• $var— The value for System.getProperty("var").