What s Next

The Basic Configuration

The Resin server requires a configuration file to handle most of its basic settings. The configuration file, called resin.conf, is located in the /conf directory one level below where Resin has been installed. Listing 2.1 contains a basic configuration file with all of the options necessary to support an initial launching of the server.

Listing 2.1: A base configuration file.

 <resin xmlns="http://caucho.com/ns/resin">   <server>     <http  app-default.xml"/>     <host id=''>       <dooument-direotory>/home/gradecki/public_html</document-directory>       <web-app id=""/>       <web-app-deploy path="webapps" />     </host>   </server> </resin> 

The Resin configuration file is based on XML and has a series of elements defined to handle all possible configuration issues. Each of the high-level elements, such as caucho.com and http-server, have additional elements defined. All of the elements available in the configuration file are shown in Appendix C. In this chapter, we discuss only the basic elements. In Chapter 15, "Resin Server Configuration," we define many more of the elements when we address advanced uses of the Resin server.

The Resin configuration file is designed for configuring the server itself. For the most part, all servlet configuration should be kept in a web.xml file located in WEB-INF. Many times, a servlet will need database information as well. The Resin system includes a file called resin-web.xml, also located in the WEB-INF directory, for setting server information for each servlet independently. We discuss both of these files as servlet examples later in Chapter 4, "Using Servlets and Resin."

The configuration shown in Listing 2.1 tells the Resin server many things about its operating environment. First, the <http> element specifies an attribute called port with a value of 8080. Obviously this tells the server that it should monitor port 8080 for all incoming HTTP requests. Notice the element itself doesn't have values associated with it but only an attribute—thus, the < /> closing tags are used. The <resin:include href="app-default.xml"/> tag pulls in a large number of server defaults which can be used as-is or overridden.

Next, the configuration file begins a section called <host>. This section deals primarily with the definition of a virtual host and specifies where the server can expect to find information on the local drives. In our example, the <host> element has a single attribute, called id. The id attribute lists hosts that could be used in the calling of a servlet. For example, multiple virtual hosts might be configured to handle the URLs http://www.yesone.com and http://www.unittest.com. For each of these URLs, you would need to set up separate directories. In our example, all URLs will use the same <host> definition. (See Chapter 17 for a discussion of virtual hosting.)

Within the <host> element are several subelements. The <document-directory> element is used to specify the document directory where source (HTML, servlet, etc.) files can be found. If this element is not present, the system will use the root directory where the server was installed. We recommend that you specify this element so the administrator of the machine has full control over file placement on the local drive.

The <web-app-deploy> element is used to specify the location of Web application resource files. By default no location is defined. The value defined in the element is appended to the document directory to form a complete directory structure. In our example, WAR files are placed in the directory /home/Gradecki/public_html/webapps. The file test.war is placed in the directory and auto-expanded to the directory webapps/test. Browsing to the application is accomplished with the URL http://localhost/test.

The HTTP Port

Within the <server> element is a subelement called <http> that lets you define the HTTP port to be used as the primary incoming channel. There are numerous attributes for this subelement, as shown in Chapter 15, but the most important is probably port. The port attribute is used to specify the port number to listen for incoming HTTP requests. The format of the subelement and attribute is as follows:

 <http port=' '/> 

If you want the port to be 80, just set it in the configuration file:

 <resin>   <server>     <http port='80'/>   </http> </resin> 

Logging in Resin 3.x

As discussed earlier, all configuration in Resin 3.x is based on a concept called the environment which allows for natural and logic separation of tasks within the configuration file. The logging definitions can be placed in several different Resin environments, including <resin>, <server>, <host-default>, <host>, <web-app-default>, and <web-app>. All logging in Resin 3.x is supported through the Logging API defined in Java 1.4. The primary element to define the logging is <log>:

 <log   name=''   path=''   level=''   rollover-period=''   timestamp= /> 

Let's break down the format of the <log> element:

• name—defines a Java-like hierarchical name

• path—where the logging should be sent. Valid values include stderr:, stdout:, and typical path names like '/usr/logs/resin/'

• level—the log level designed to match the levels defined for Java 1.4 logging. The values available are shown in Table 2.2.

  Table 2.2: Java 1.4 Logging Values

  NAME	JAVA 1.4 LOGGING API	MEANING
  off		no logging
  severe	severe	severe issue with the application
  warning	warning	possible problem has occurred and needs attention
  info	Info	information only
  config	Config	configuration issue
  fine	Fine	course tracing information
  finer	Finer	more detailed tracing message
  finest	Finest	detailed tracing message
  all		log everything

• rollover-period—Specifies the frequency in days, weeks, or months before a new rollover file is created.

• timestamp—Specifies the format for stamping each of the logging output lines. The format values are shown in Table 2.3. For example:

   <resin xmlns=http://caucho.com/ns/resin>   <log name='' path='stdout:' rollover-period='1W/> </resin> 

  Table 2.3: Logging Timestamp Formatting Specification

  VALUE	DESCRIPTION
  %a	short weekday (mon)
  %A	long weekday (Monday)
  %b	short month (Jan)
  %B	long month (January)
  %c	date specific to executing locale
  %d	day of month
  %H	24-hour
  %l	12-hour
  %j	day of year
  %m	month
  %M	minute
  %p	am/pm
  %S	seconds
  %s	milliseconds
  %W	week of year
  %w	day of week
  %y	2-digit year
  %Y	4-digit year

The Java Compiler

The Resin server needs access to a Java compiler in order to compile JSP pages and build corresponding servlets. The <javac> element allows you to specify Java compiler information to be passed to the server. The format of the element is as follows:

 <resin>   <javac compiler=' '     compiler-args=''     encoding=''/> </resin> 

In this format:

• compiler —Specifies a path to a Java compiler like that supplied in the Java JDK or a just-in-time compiler. The default value is internal, which instructs the server to find a Java compiler based on where one would normally be found.

• -args —Contains a string of additional arguments to pass through to the Java compiler when it is invoked.

• encoding —Specifies the character encoding you want to use.

The Error Page

It is probably fair to say that everyone has experienced a Web site error in which a browser message appears with an error code (such as 404). Associated with the error code is a fair amount of descriptive text explaining what might have occurred. With some sites a missing page doesn't display a 404 error but instead displays a "nice" page with the site's graphics and logos. The Resin server allows a specific error page to be displayed in the event that a request fails. The <error-page> element handles the configuration:

 <web-app id='/'>   <error-page location=''                       exception-type=''                       error-code=''   /> </web-app> 

In this format:

• location —Specifies the path to the file you want to display for a given exception or error code.

• exception-type —Contains a string representing a valid Java exception.

• error-code —Specifies a valid HTTP status code.

The <error-page> element is placed within a <web-app> element. The <web-app> element is used to define configuration parameters for applications being served by Resin (see Chapter 15). The tag <web-app > tells the Resin server to apply configuration information enclosed within the tag to all Web applications. For example, when the error code 404 is received it indicates that the page being requested cannot be found. The Web server generally returns a basic error page. You can place the following elements in the configuration file to display a more informative page when the error code is received:

 <web-app id='/'>   <error-page location='errors/404errorpage.jsp'                       error-code='404'   /> </web-app> 

With this configuration, the page 404errorpage.jsp is displayed when a page cannot be found.

There are also times when a Java class will return an exception. Probably the most notable is the error java.lang.NullPointerException. Using the <error-page> element, you can display an error page for exceptions as well. For example:

 <web-app id='/'>   <error-page location='errors/404errorpage.jsp'                       exception-type='java.lang.NullPointerException'   /> </web-app> 

It is possible to have a host-wide errorpage by including a <error-page> element under the <host> element.

The Server Restart Ping

During development work or in a production situation, the worst thing that can happen is to have your server crash or just become unavailable. To solve this problem, you can set up a monitor that can constantly ping the server to verify that not only is it alive but that a specific Web site is running on the server. The Resin server features this monitor capability, and you can set it up through the configuration file.

The monitoring of the server and hosted Web sites is accomplished using a separate thread, which acts like a simple Web browser to access a number of URLs. As long as the listed URLs return a result or HTTP status 200, it can be assumed the server and Web site are operational. If a failure does occur, the thread kills Resin and forces a restart of the server. Note that the separate thread executing to determine if the server is still alive executes in the JVM where the server is executing. If by chance the virtual machine hangs, the server will have essentially crashed without detection.

The ping functionality is handled through a resource. For example:

 <resource jndi-name="ping" type="com.caucho.server.admin.PingThread">   <init>     <url>http://localhost:8080/index.jsp</url>     <sleep-time>15s</sleep-time>   </init> </resource> 

Using a <resource> allows the system to handle the execution of the ping thread and offload any special configuration. If you want to write your own ping class, place the newly created class name in the 'type' attribute.