<title>A Hello, World Servlet</title>

<p/>Servlets are the pure Java solution to handle web requests.  Many
application will use servlets instead of JSP and others will use servlets
in conjunction with JSP.  Experienced JSP programmers use servlets
in conjunction with JSP to create clearer and simpler applications.
The servlets handle Java processing: form handing, calculation and
database queries.  JSP formats the results.

<p/>Servlets belong in <ct:var>doc/WEB-INF/classes</ct:var>.  On this machine,
you'll put the Java source in <ct:var><jsp:expression>
application.getRealPath("/WEB-INF/classes")
</jsp:expression></ct:var>.  WEB-INF/classes is the standard location
for servlets and other Java classes.  Resin automatically reloads and
recompiles servlets, beans, and classes placed in WEB-INF/classes.
You should make some changes and add errors to become familiar with Resin's
recompilation and the error reporting.

<p/>Create the following servlet in
<ct:var>WEB-INF/classes/test/HelloWorld.java</ct:var> with your favorite
text editor: notepad, emacs, vi, or whatever.  (On this machine,
<ct:var><jsp:expression>
  application.getRealPath("/WEB-INF/classes/test/HelloWorld.java")
</jsp:expression></ct:var>)

<ct:example title='WEB-INF/classes/test/HelloWorld.java'>
package test;

import java.io.*;

import javax.servlet.http.*;
import javax.servlet.*;

public class HelloWorld extends HttpServlet {
  public void doGet (HttpServletRequest req,
                     HttpServletResponse res)
    throws ServletException, IOException
  {
    PrintWriter out = res.getWriter();

    out.println("Hello, world!");
    out.close();
  }
}
</ct:example>

<p/>Now browse the servlet at <jsp:expression>
"http://" + request.getServerName() + ":" + request.getServerPort() +
request.getContextPath() + "/servlet/test.HelloWorld"
</jsp:expression>.  Resin will automatically compiles the servlet for you.
Browsing servlets differs from page browsing because
you're executing a servlet class, not looking at a page.
The <ct:var>/servlet</ct:var> URL tells Resin to look for a servlet. 

<section title='Configuration'>

<p/>The default resin.conf in the distribution is already configured for
the example, so you can just start Resin as described in
the <a href="../ref/httpd.xtp">standalone server</a>.  Not all of the
standard resin.conf is necessary for this example, though.  You can cut it
down to the following configuration.

For development, using the <ct:var>/servlet</ct:var> invoker is
convenient.  The invoker servlet will let you specify the servlet class
in the URL itself, like /servlet/test.HelloWorld.  Its configuration in
the resin.conf looks like:

<ct:example>
&lt;caucho.com>
&lt;http-server>
  &lt;http port='8080'/>

  &lt;host id=''>
    &lt;app-dir>doc&lt;/app-dir>

    &lt;web-app id='/'>
      &lt;servlet-mapping url-pattern='/servlet/*'
                       servlet-name='invoker'/>
    &lt;/web-app>
  &lt;/host>
&lt;/http-server>
&lt;/caucho.com>
</ct:example>

Resin allows a short cut for the XML configuration in the example above;
you can use XML attributes in place of elements.  The
Servlet 2.3 standard uses only elements.  So the servlet-mapping
configuration following the Servlet 2.3 standard would look like:

<ct:example>
&lt;servlet-mapping>
  &lt;url-pattern>/servlet/*&lt;/url-pattern>
  &lt;servlet-name>invoker&lt;/servlet-name>
&lt;/servlet-mapping>
</ct:example>

The two are entirely equivalent.  For larger configurations, using attributes
makes the resin.conf or web.xml more readable.

<deftable>
<tr><th>tag<th>meaning
<tr><td>caucho.com<td>Top-level tag for all Caucho configuration
<tr><td>http-server<td>Configuration for the servlet engine (both http and srun)
<tr><td><a href="../ref/http-config.xtp#http">http</a><td>Configures a
standalone HTTP server.  You can listen multiple &lt;http> or
<a href="../ref/http-config.xtp#srun">&lt;srun></a> ports at once.
<tr><td>port<td>The TCP port to listen to.  When actually deploying Resin,
you'll use port 80, but port 8080 is a good development port.
<tr><td><a href="../ref/http-config.xtp#host">host</a><td>Configures the
default <a href="../ref/virtual-host.xtp">virtual host</a>.  Many sites will
only need the default.
<tr><td><a href="../ref/app-config.xtp#app-dir">app-dir</a><td>The document
directory for the virtual host.  You can change this to the location of the
real document root.
<tr><td><a href="../ref/app-config.xtp">web-app</a><td>Configures the root
web-app for this virtual host.  Most sites will only need the root web-app.
<tr><td><a href="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a><td>Specifies the URL to servlet mapping.
<tr><td><a href="../ref/app-config.xtp#url-pattern">url-pattern</a><td>Which
URL should map to the servlet.
<tr><td><a href="../ref/app-config.xtp#servlet-name">servlet-name</a><td>The
servlet to invoke for the URL.  In this case, the special "invoker" which
looks up the class from the URL.
</deftable>

This example just uses the default virtual host and root web-app.  Many
sites will just use the default virtual host and root web-app.  For now, you
can ignore them and concentrate on the other configuration.

<p/>The example configuration is a complete working configuration.  You can
create a configuration file in resin-2.0.x/conf/test.conf to test it out.

<example title='Starting on Windows'>
resin-2.0.x> bin\httpd -conf test.conf
</example>

<example title='Starting on Unix'>
resin-2.0.x> bin/httpd.sh -conf test.conf
</example>

<p/>If you run into any trouble trying to start Resin, look at
the <a href="../ref/httpd.xtp">standalone HTTP server</a> page.

</section>
