<s1 title="Servlet"><p>Servlets are Java classes which service HTTP requests.  The onlyrequirement for writing a servlet is that it implements thejavax.servlet.Servlet interface.</p><p>Servlets are loaded from the classpath like all Java classes.Normally, users put servlets in <var/WEB-INF/classes/> so Resin willautomatically reload them when they change.</p><p><a href='jsp.xtp'>JSP</a> pages are implemented asServlets, and tend to be more efficient for pages with lots of text.</p><s2 title='Examples'><s3 title='Configuring the web.xml'><p>The following is a complete working web.xml to run this example.</p><p>The <var/servlet-mapping/> tells Resin that the URL<var//hello/> should invoke the <var/hello-world/> servlet.</p><p>The <var/servlet/> tells Resin that <var/hello-world/> uses the<var/test.HelloWorld/> class and that the value of the <var/greeting/>init parameter is <var/Hello World/>.</p><example title='WEB-INF/web.xml'>&lt;web-app>  &lt;servlet-mapping url-pattern='/hello'                   servlet-name='hello-world'/>  &lt;servlet servlet-name='hello-world'           servlet-class='test.HelloWorld'>    &lt;init-param greeting='Hello, World'/>&lt;/web-app></example><p>The Java code, <var/HelloWorld.java/> belongs in</p><def>$app-dir/WEB-INF/classes/test/HelloWorld.java</def><p>Or, if you're compiling the servlet yourself, the class file belongs in</p><def>$app-dir/WEB-INF/classes/test/HelloWorld.class</def><p>Following is the actual servlet code.  It just prints a trivialHTML page filled with the greeting specified in the web.xml.</p><p><var/init()/> and <var/destroy()/> are included mostly forillustration.  Resin will call <var/init()/> when it starts the servletand <var/destroy/> before Resin destroys it.</p><example>package test;import java.io.*;import javax.servlet.*;import javax.servlet.http.*;public class HelloWorld extends HttpServlet {  private String greeting;  public void init()    throws ServletException  {    greeting = getInitParameter("greeting");  }  public void doGet(HttpServletRequest request,                    HttpServletResponse response)    throws ServletException, IOException  {    PrintWriter out = response.getWriter();    out.println("&lt;title>" + greeting + "&lt;/title>");    out.println("&lt;h1>" + greeting + "&lt;/h1>");  }    public void destroy()  {    // nothing to do  }}</example></s3><s3 title='Servlet Example for JSP Programmers'><p>Because Resin compiles JSP pages into servlets, programmers familiarwith JSP can start writing servlets fairly easily.  The following templatecan be used to see how to write a servlet for someone familiar with JSP.</p><example>package test;import java.io.*;import javax.servlet.*;import javax.servlet.http.*;public class HelloWorld extends HttpServlet {  public void service(HttpServletRequest request,  		      HttpServletResponse response)    throws ServletException, IOException  {    PrintWriter out = response.getWriter();    ServletContext application = getServletContext();    HttpSession session = request.getSession();    try {      // <var/code goes here/>      // The equivalent of jsp:include:      // request.getRequestDispatcher("/inc.jsp").include(request, response);    } catch (ServletException e) {      throw e;    } catch (Exception e) {      throw new ServletException(e);    }  }}</example></s3><s3 title='Using Databases from a Servlet'><p>The following is a sample design pattern for getting new databaseconnections.  The <var/try ... finally/> block is very important.  Withoutthe close in the finally block, Resin's database pool can loose connections.</p><p>Configuring the database is described in the<a href="db-config.xtp">database configuration</a> page.</p><example title="TestDatabase.java">package test;import java.io.*;import java.sql.*;import javax.servlet.*;import javax.servlet.http.*;import javax.naming.*;import javax.sql.*;public class TestDatabase extends HttpServlet {  DataSource pool;  public void init()    throws ServletException  {    try {      Context env = (Context) new InitialContext().lookup("java:comp/env");      pool = (DataSource) env.lookup("jdbc/test");      if (pool == null)        throw new ServletException("`jdbc/test' is an unknown DataSource");    } catch (NamingException e) {      throw new ServletException(e);    }  }  public void doGet(HttpServletRequest request,                    HttpServletResponse response)    throws IOException, ServletException  {    response.setContentType("text/html");    PrintWriter out = response.getWriter();    Connection conn = null;    try {      conn = pool.getConnection();      // <var/code for the servlet using the database goes here/>      rs.close();      stmt.close();    } catch (SQLException e) {      throw new ServletException(e);    } finally {      try {        if (conn != null)          conn.close();      } catch (SQLException e) {      }    }  }}</example></s3></s2><s2 title="Servlet Configuration"><defun title='init-param'><p>Initializes servlet variables. <code/servlet-param/>defines initial values for <code/getServletConfig().getInitParameter("foo")/>.</p><p>The full servlet 2.2 syntax is supported and allows a simple shortcut.</p><example>&lt;web-app id='/'&gt;&lt;servlet servlet-name='test.HelloWorld'&gt;  &lt;init-param foo='bar'/&gt;  &lt;init-param&gt;    &lt;param-name&gt;baz&lt;/param-name&gt;    &lt;param-value&gt;value&lt;/param-value&gt;  &lt;/init-param&gt;&lt;/servlet&gt;&lt;/web-app></example></defun><defun title="load-on-startup"><p>If present, starts the servlet when the server starts.</p><example>&lt;web-app id='/'>&lt;servlet servlet-name='hello'         servlet-class='test.HelloWorld'&gt;  &lt;load-on-startup/&gt;&lt;/servlet&gt;&lt;/web-app&gt;</example></defun><defun title='run-at' version='Resin 1.1'><p>If present, calls the servlet's <var/service()/> methodat the specified times.&lt;run-at> lets servlet writers execute periodic tasks without worryingabout creating a new Thread.</p><p>The value is a list of 24-hour times when theservlet should be automatically executed.  To run the servlet every 6hours, you could use:</p><example>&lt;servlet servlet-name='test.HelloWorld'&gt;  &lt;run-at&gt;0:00, 6:00, 12:00, 18:00&lt;/run-at&gt;&lt;/servlet&gt;</example><p>If the hour is omitted, the servlet runs every hour at thespecified minute.  To run the server every 15 minutes, you could use:</p><example>&lt;servlet servlet-name='test.HelloWorld'&gt;  &lt;run-at&gt;:00, :15, :30, :45&lt;/run-at&gt;&lt;/servlet&gt;</example></defun><defun title='servlet'><p>Defines a servlet alias for later mapping.</p><deftable><tr><th>Attribute<th>Description<tr><td>servlet-name<td>The servlet's name (alias)<tr><td>servlet-class<td>The servlet's class (defaults to servlet-name)<tr><td>init-param<td>Initialization parameters<tr><td>load-on-startup<td>Initializes the servlet when the server starts.<tr><td>run-at<td>Times to execute the servlet automatically</deftable><p>The following example defines a servlet alias 'hello'</p><example>&lt;web-app id='/'&gt;&lt;servlet-mapping url-pattern='/hello.html'                 servlet-name='hello'/&gt;&lt;servlet servlet-name='hello'         servlet-class='test.HelloWorld'&gt;  &lt;init-param title='Hello, World'/&gt;&lt;/servlet&gt;&lt;servlet servlet-name='cron'         servlet-class='test.DailyChores'&gt;  &lt;run-at&gt;3:00&lt;/run-at&gt;&lt;/servlet&gt;&lt;/web-app&gt;</example></defun><defun title='servlet-class'><p>Class of the servlet.  The CLASSPATH for servlets includesthe WEB-INF/classes directory and all jars in the WEB-INF/lib directory.</p></defun><defun title='servlet-name'><p>Alias of the servlet.</p></defun><defun title="servlet-mapping"><p>Maps from a URL to the servlet to execute.  The servlet-mappinghas a url-pattern to match the URL and a servlet-name to match theconfigured servlet.</p><example title="typical servlet-mapping">&lt;servlet>  &lt;servlet-name>hello&lt;/servlet-name>  &lt;servlet-class>test.HelloServlet&lt;/servlet-class>&lt;/servlet>&lt;servlet-mapping>  &lt;url-pattern>/hello/*&lt;/url-pattern>  &lt;servlet-name>hello&lt;/servlet-name>&lt;/servlet-mapping></example><p>Resin allows for a shortcut combining the servlet andthe servlet mapping:</p><example title="shortcut servlet-mapping">&lt;servlet-mapping url-pattern="/hello/*"                 servlet-class="test.HelloServlet"/></example></defun><defun title="url-pattern" version="Servlet 2.2"><p>Matches a set of URLs for servlet-mapping.</p><deftable><tr><th width='25%'>Pattern<th>Description<tr><td>/foo/bar.html<td>Matches exactly the /foo/bar.html URL.<tr><td>/foo/*<td>Matches /foo and any children<tr><td>*.foo<td>Matches any URL with a .foo extension<tr><td>/<td>Replaces the default servlet.</deftable><p><var///> defines a default handler and <var//*/> defines a prefix handler.<var//*/> will override extension handlers like <var/*.foo/>. <var///>will only be used if no other pattern matches.</p><p>No default.  Either url-pattern or url-regexp is required.</p></defun></s2></s1>