Hello World Servlet

Configuring Resin

As we mentioned earlier, servlets are typically found in the WEB-INF/classes directory of an application directory under the /doc directory of the Resin installation. The resin.conf file contains a <web-app> element, which has an id attribute with a path value to the application. For example, here's an entry for an application under the /hello directory of/doc:

   <web-app id='/hello'/> 

With this entry, Resin attempts to find application source files in the directory /doc/hello/WEB-INF/classes. The <web-app> element has many subelements for complete control over the application (see Chapter 15). You can either put the information from the application in the resin.conf file under the <web-app> element or create a web.xml file in the WEB-INF directory.

The web.xml file encapsulates all of the application's information. The following is a basic web.xml file for a servlet in the /hello application directory:

 <web-app xmlns="http://caucho.com/ns.resin"> <servlet servlet-name='HelloWorld' servlet-class='example.Hello'> <servlet-mapping url-pattern='/hello' servlet-name='HelloWorld'/> </web-app> 

In this sample web.xml file, the <servlet-mapping> element is used to perform a match against the URL passed to the server. If the URL includes the pattern "/hello", the "HelloWorld" servlet reference name should be used (note this isn't the name of the Java class that should be used). The "HelloWorld" servlet reference name is related to a classname using the <servlet> element. Within this element is an attribute called servlet-name, which relates to the name attribute in the <servlet-mapping> element. This reference name is mapped to the class test.HelloWorld. The Resin server attempts to load the class HelloWorld in the /WEB-INF/classes/test directory.

Web Defaults in Resin 3.x

With Resin 3.x, defaults can be applied to Web application using a new element called <web-app-default>. This element can be applied to the <server>, <host>, and <host-default> environments. Before a specific web.xml file is applied to a Web application, all of the tags defined within <web-app-default> will be applied first. The web.xml file will override any defaults defined for a specific server or host.

The <web-app-default> element can appear in the elements listed above or can placed in the file /conf/app-default.xml. When placed in the app-default.xml file, they are executed before any web.xml file. The elements available in <web-app-default> are shown in Chapter 15, "Resin Server Configuration." Following is an example:

 <web-app-defaults>   <class-loader>      <compiling-loader path='WEB-INF/classes'/>     <library-loader path='WEB-INF/lib'/>   </class-loader>   <servlet servlet-name="jsp"                 serlet-/>   <servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/> </web-app-defaults> 

Resin web.xml Elements

The Resin server recognizes many different elements within the <web-app> element in the web.xml file. Let's take a close look at those elements.

<servlet-mapping>

One of the most important things the web.xml file does is provide information about the mapping from a URL to a servlet. When a user or another Web page uses a URL containing a servlet, the Resin server must have a way to determine what servlet class to execute. The URL provided by the browser might specifically state the intended servlet classname, or it might be an arbitrary string. You use the <servlet-mapping> element to map possible servlet names to an actual classname.

Consider the following snippet:

 <servlet-mapping>   <url-pattern>/CA/*</url-pattern>   <servlet-name>CAServlet</servlet-name> </servlet-mapping> 

In this mapping, you tell Resin to check the URL for a pattern like /CA/ that ends with any string value. If the URL looks like this sample pattern, Resin should execute the CAServlet servlet. The CAServlet is just a reference name; a <servlet> element is needed to find the actual servlet class. A <web-app> element can have any number of these <servlet-mapping> elements. For example:

 <servlet-mapping>   <url-pattern>/CA/CAServlet</url-pattern>   <servlet-name>CAServlet</servlet-name> </servlet-mapping> <servlet-mapping>   <url-pattern>/CA/Login</url-pattern>   <servlet-name>CALoginServlet</servlet-name> </servlet-mapping> 

Here we have two specific servlets and the patterns a URL must have in order for Resin to execute them.

<url-pattern>

The <url-pattern> is very important; it is the only mechanism available to the server to match URLs. Matching will occur:

• On an exact match like /CA/Login

• Using wildcards, such as /CA/*

• With extension wildcards, such as /CA/*.srv

• By default with /

The / pattern can be important if you want to provide a page for users who don't supply a correct URL pattern. The /* pattern will override the *.srv pattern. If you need more control over the matching, you can use the <url-reg-exp> element (see Chapter 15).

<servlet>

Once a URL has been mined and matches against a servlet name, Resin matches the name against a <servlet> element. The <servlet> element acts as the link between the URL and the actual servlet class that Resin will execute. A typical <servlet> element looks like those in the following example:

 <web-app xmlns="http://caucho.com/ns/resin" >   <servlet servlet-name='CALogin'            servlet-class='ca.Login'>   </servlet>   <servlet-mapping url-pattern='/login.html'                    servlet-name='CALogin'/>   <servlet servlet-name='cleanup'            servlet-class='ca.Cleanup'>   </servlet> </web-app> 

In this example, we see two different <servlet> elements. The first matches the directory with the <servlet-mapping> for the login.html URL. When a match is made, the <servlet-name> elements match each other and the ca.Login class is executed.

The <servlet> element can contain several subelements:

• <servlet-name>

• <servlet-class>

• <init-param>

• <load-on-startup>

<servlet-name>

You use the <servlet-name> subelement to define an alias name and to link the servlet to a URL through the <servlet-mapping> element. The name must be unique within the <web-app> element. It is entirely possible to have multiple servlets of the same classname but that have different aliases. In these cases, the <init-param> values are likely to be different.

<servlet-class>

The <servlet-class> subelement defines the actual Java class that Resin should execute when the alias is matched. Resin checks the WEB-INF/classes directory for the class by default (as well as the /WEB-INF/lib directory if a JAR file is involved).

<init-param>

Later in this chapter, we show you how to write a servlet that can obtain initialization parameters defined by the <init-param> subelement. The format of the element is

 <init-param key='value'> 

The servlet has the ability to request the value of the key parameter and use that value as needed in the servlet.

<load-on-startup>

The <load-on-startup> element tells the Resin server to automatically load and start the servlet when the server starts. The server finds the servlet, loads it, instantiates an object, and executes the init() method. Without this element, the server loads the servlet only when a request is made from a browser or application. The following is an example web.xml configuration:

 <web-app id='/'>   <servlet servlet-name='hello'            servlet-class='example.Hello'>     <load-on-startup/>   </servlet>   <servlet-mapping url-pattern='/hello'                    servlet-name='HelloWorld'/> </web-app> 

Place the <load-on-startup> element within the <servlet> element to control the loading of individual servlets.

A Shortcut

In many cases, writing both the <servlet-mapping> and <servlet> elements separately is redundant. Resin lets you combine these two elements into the <servlet-mapping> element. For example, the following elements can be combined:

 <web-app id='/'>   <servlet servlet-name='hello'            servlet-class='example.Hello'>   </servlet>   <servlet-mapping url-pattern='/hello'                    servlet-name='HelloWorld'/> </web-app> 

The new <servlet-mapping> element is:

 <web-app id='/'>   <servlet-mapping url-pattern='/hello'                    servlet-class='example.Hello' /> </web-app> 

This shortcut is currently disabled in Resin 3.1, but it is expected to return in a future version of the server.