## groovy.servlet
Class TemplateServlet

    java.lang.Object
      javax.servlet.GenericServlet
          javax.servlet.http.HttpServlet
              groovy.servlet.AbstractHttpServlet
                  groovy.servlet.TemplateServlet

All Implemented Interfaces:
  ResourceConnector, Serializable, Servlet, ServletConfig

    public class TemplateServlet

extends AbstractHttpServlet

A generic servlet for serving (mostly HTML) templates.

It delegates work to a `groovy.text.TemplateEngine` implementation processing HTTP requests.

#### Usage

`helloworld.html` is a headless HTML-like template

      <html>
        <body>
          <% 3.times { %>
            Hello World!
          <% } %>
          <br>
        </body>
      </html>

Minimal `web.xml` example serving HTML-like templates

     <web-app>
       <servlet>
         <servlet-name>template</servlet-name>
         <servlet-class>groovy.servlet.TemplateServlet</servlet-class>
       </servlet>
       <servlet-mapping>
         <servlet-name>template</servlet-name>
         <url-pattern>*.html</url-pattern>
       </servlet-mapping>
     </web-app>

#### Template engine configuration

By default, the TemplateServer uses the `SimpleTemplateEngine` which interprets JSP-like templates. The init parameter `template.engine` defines the fully qualified class name of the template to use:

       template.engine = [empty] - equals groovy.text.SimpleTemplateEngine
       template.engine = groovy.text.SimpleTemplateEngine
       template.engine = groovy.text.GStringTemplateEngine
       template.engine = groovy.text.XmlTemplateEngine

#### Logging and extra-output options

This implementation provides a verbosity flag switching log statements. The servlet init parameter name is:

       generate.by = true(default) | false

Version:
  2.0
Author:
  Christian Stein, Guillaume Laforge
See Also:
  `setVariables(ServletBinding)`, Serialized Form

Field Summary

Fields inherited from class groovy.servlet.AbstractHttpServlet
`CONTENT_TYPE_TEXT_HTML, encoding, INC_PATH_INFO, INC_REQUEST_URI, INC_SERVLET_PATH, reflection, resourceNameMatcher, resourceNameReplaceAll, resourceNameReplacement, servletContext, verbose`

Constructor Summary
`TemplateServlet()` Create new TemplateSerlvet.

Method Summary
`protected Template` `getTemplate(File file)` Gets the template created by the underlying engine parsing the request.
`void` `init(ServletConfig config)` Initializes the servlet from hints the container passes.
`protected TemplateEngine` `initTemplateEngine(ServletConfig config)` Creates the template engine.
`void` `service(HttpServletRequest request, HttpServletResponse response)` Services the request with a response.
`protected void` `setVariables(ServletBinding binding)` Override this method to set your variables to the Groovy binding.

Methods inherited from class groovy.servlet.AbstractHttpServlet
`getResourceConnection, getScriptUri, getScriptUriAsFile`

Methods inherited from class javax.servlet.http.HttpServlet
`doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service`

Methods inherited from class javax.servlet.GenericServlet
`destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### TemplateServlet

    public TemplateServlet()

  Create new TemplateSerlvet.

Method Detail

### getTemplate

    protected Template getTemplate(File file)
                            throws ServletException

  Gets the template created by the underlying engine parsing the request.

  This method looks up a simple (weak) hash map for an existing template object that matches the source file. If the source file didn't change in length and its last modified stamp hasn't changed compared to a precompiled template object, this template is used. Otherwise, there is no or an invalid template object cache entry, a new one is created by the underlying template engine. This new instance is put to the cache for consecutive calls.

  Parameters:
    `file` - The HttpServletRequest.
  Returns:
    The template that will produce the response text.
  Throws:
    `ServletException` - If the request specified an invalid template source file

### init

    public void init(ServletConfig config)
              throws ServletException

  Initializes the servlet from hints the container passes.

  Delegates to sub-init methods and parses the following parameters:

  - `"generatedBy"` : boolean, appends "Generated by ..." to the HTML response text generated by this servlet.

  Specified by:
    `init` in interface `Servlet`
  Overrides:
    `init` in class `AbstractHttpServlet`
  Parameters:
    `config` - Passed by the servlet container.
  Throws:
    `ServletException` - if this method encountered difficulties
  See Also:
    `initTemplateEngine(ServletConfig)`

### initTemplateEngine

    protected TemplateEngine initTemplateEngine(ServletConfig config)

  Creates the template engine. Called by `init(ServletConfig)` and returns just `new groovy.text.SimpleTemplateEngine()` if the init parameter `template.engine` is not set by the container configuration.

  Parameters:
    `config` - Current serlvet configuration passed by the container.
  Returns:
    The underlying template engine or `null` on error.

### service

    public void service(HttpServletRequest request,
                        HttpServletResponse response)
                 throws ServletException,
                        IOException

  Services the request with a response.

  First the request is parsed for the source file uri. If the specified file could not be found or can not be read an error message is sent as response.

  Overrides:
    `service` in class `HttpServlet`
  Parameters:
    `request` - The http request.
    `response` - The http response.
  Throws:
    `IOException` - if an input or output error occurs while the servlet is handling the HTTP request
    `ServletException` - if the HTTP request cannot be handled

### setVariables

    protected void setVariables(ServletBinding binding)

  Override this method to set your variables to the Groovy binding.

  All variables bound the binding are passed to the template source text, e.g. the HTML file, when the template is merged.

  The binding provided by TemplateServlet does already include some default variables. As of this writing, they are (copied from `ServletBinding`):

  - `"request"` : HttpServletRequest
  - `"response"` : HttpServletResponse
  - `"context"` : ServletContext
  - `"application"` : ServletContext
  - `"session"` : request.getSession(false)

  And via implicite hard-coded keywords:

  - `"out"` : response.getWriter()
  - `"sout"` : response.getOutputStream()
  - `"html"` : new MarkupBuilder(response.getWriter())

  Example binding all servlet context variables:

       class Mytlet extends TemplateServlet {

         protected void setVariables(ServletBinding binding) {
           // Bind a simple variable
           binding.setVariable("answer", new Long(42));

           // Bind all servlet context attributes...
           ServletContext context = (ServletContext) binding.getVariable("context");
           Enumeration enumeration = context.getAttributeNames();
           while (enumeration.hasMoreElements()) {
             String name = (String) enumeration.nextElement();
             binding.setVariable(name, context.getAttribute(name));
           }
         }

       }

  Parameters:
    `binding` - to be modified

Copyright © 2003-2008 The Codehaus. All rights reserved.