Package: groovy.servlet

## [Java] Class TemplateServlet

- groovy.servlet.TemplateServlet

- 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

  ### Servlet Init Parameters

  #### Logging and extra-output options

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

         generated.by = true(default) | false

  #### Groovy Source Encoding Parameter

  The following servlet init parameter name can be used to specify the encoding TemplateServlet will use to read the template groovy source files:

         groovy.source.encoding

  See Also:
    TemplateServlet.setVariables

- - Inherited fields
    Fields inherited from class | Fields
    --- | ---
    `class AbstractHttpServlet` | `CONTENT_TYPE_TEXT_HTML, INC_PATH_INFO, INC_REQUEST_URI, INC_SERVLET_PATH, INIT_PARAM_RESOURCE_NAME_REGEX, INIT_PARAM_RESOURCE_NAME_REGEX_FLAGS, encoding, namePrefix, reflection, resourceNamePattern, resourceNameReplaceAll, resourceNameReplacement, servletContext, verbose`

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `def` | `TemplateServlet()` Create new TemplateServlet.
    `` | `protected Template` | `getTemplate(File file)` Gets the template created by the underlying engine parsing the request.
    `` | `protected Template` | `getTemplate(URL url)` 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.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class AbstractHttpServlet` | `applyResourceNameMatcher, generateNamePrefixOnce, getResourceConnection, getScriptUri, getScriptUriAsFile, init, removeNamePrefix, setVariables`

- - ### Method Detail

    - #### public def TemplateServlet()

      Create new TemplateServlet.

    - #### protected Template getTemplate(File file)

      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.

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

    - #### protected Template getTemplate(URL url)

      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 URL. If there is no cache entry, a new one is created by the underlying template engine. This new instance is put to the cache for consecutive calls.

      throws:
        ServletException If the request specified an invalid template source URL
      Returns:
        The template that will produce the response text.
      Parameters:
        `url` - The URL containing the template source..

    - #### public void init(ServletConfig config)

      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.
      throws:
        ServletException if this method encountered difficulties
      Parameters:
        `config` - Passed by the servlet container.
      See Also:
        TemplateServlet.initTemplateEngine

    - #### protected TemplateEngine initTemplateEngine(ServletConfig config)

      Creates the template engine.

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

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

    - #### public void service(HttpServletRequest request, HttpServletResponse response)

      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.

      throws:
        IOException if an input or output error occurs while the servlet is handling the HTTP request
      throws:
        ServletException if the HTTP request cannot be handled
      Parameters:
        `request` - The http request.
        `response` - The http response.