TeaServlet Configuration

Table of Contents | Next - Plugins

Servlet Configuration

As with any servlet-based framework, the TeaServlet contains an actual servlet that must be provided in the web.xml configuration. The TeaServlet servlet is conveniently named org.teatrove.teaservlet.TeaServlet. The following is the most basic example of a configuration:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5">
    <servlet>
        <servlet-name>TeaServlet</servlet-name>
        <servlet-class>org.teatrove.teaservlet.TeaServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>TeaServlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

This example registers the TeaServlet and binds it to any path. TeaServlet routes requests to a Tea file named the same as the path. For example, the URL http://localhost:8080/context/about/location would load the about/location.tea template. For more information on routing within the TeaServlet, see TeaServlet Lifecycle.

As part of the TeaServlet initialization, it loads a TeaServlet configuration file that configures the servlet. By default, this is either the /WEB-INF/teaservlet.xml or /WEB-INF/teaservlet.properties file, but may be overridden by the properties.file initialization parameter. The TeaServlet also supports the following initialization parameters.

debug This specifies a boolean expression of whether detailed logging statements should be output to the servlet log during initialization of the TeaServlet. The default is false.

properties.file This specifies the path of the TeaServlet configuration file. The default is either /WEB-INF/teaservlet.xml or /WEB-INF/teaservlet.properties, depending on which file exists. TeaServlet supports two types of configuration formats: XML and enhanced properties. See [LINK TO SECTION] for more information. The path is relative to the web application, although it may also use any URL-supported protocol such as file: or http:. See [LINK TO SECTION] for more information on how configuration resources are accessed.

properties.factory.class This specifies the fully-qualified class name of a class that implements the org.teatrove.trove.util.PropertyMapFactory interface and contains a constructor that takes a java.util.Map. The map parameter will either be an empty map or be the properties defined by the properties.factory.init configuration. The factory class provides the ability to load properties in alternative means. For more information on property factories, see [LINK TO SECTION].

substitutions.file This specifies the path to a properties file that contains key/value pairs that may be used within TeaServlet configuration files as variable expressions (ie: ${property.name}). The path is relative to the web application, although it may also use any URL-supported protocol such as file: or http:. See [LINK TO SECTION] for more information on how configuration resources are accessed.

substititions.env This specifies a boolean expression of whether the system environment variables should be loaded as substitution properties. The default is true.

substitutions.system This specifies a boolean expression of whether the system properties (ie: -Dproperty=value) should be loaded as substitution properties. The default is true.

substitutions.properties This specifies a map of properties that should be loaded as substitution properties. This allows the properties to be used inline with the configuration rather than as a separate properties file.

substitutions.factory.class This specifies the fully-qualified class name of a class that implements the org.teatrove.trove.util.PropertyMapFactory interface and contains a constructor that takes a java.util.Map. The map parameter will either be an empty map or be the properties defined by the substitutions.factory.init configuration. The factory class provides the ability to load substitution properties in alternative means. For more information on property factories, see [LINK TO SECTION].

Resource Factories

TeaServlet uses a custom org.teatrove.trove.util.resources.ResourceFactory class to load external configuration files.
TeaServlet, by default, creates a custom resource factory (org.teatrove.teaservlet.TeaServletResourceFactory) that supports loading resources by the following mechanisms:

• Local file system relative to the startup directory of the servlet container. This is not recommended as it is not portable from container to container and not all containers support file-based operations. Paths may include the optional file: protocol.

• Web application resources relative to the web application. The paths must begin with a leading '/' (ie: /WEB-INF/teaservlet.xml). Paths may include the optional web: protocol.

• Class path artifacts relative to the class loader of the web application (ie: META-INF/teaservlet.xml). Paths may include the optional classpath: protocol.

• Any java.net.URL supported resource such as http:, https:, ftp:, etc. The paths must contain the associated protocol and the resource factory delegates to the underlying URL implementation of the JVM.

The ResouceFactory may lookup a resource as a URL, as an input stream, or as a set of properties using the property map factory support. Further, you may pass in custom substitutions to automatically evaluate property expressions.

Property Map Factories

TeaServlet loads configuration files and the associated properties using custom org.teatrove.trove.util.PropertyMapFactory implementations. The default implementation supports loading both XML-based formats and enhanced property formats. See [INCLUDE LINK] for more information on the formats. Custom property map factories may be used to provide custom support. The following rules must be met.

• Implement the org.teatrove.trove.util.PropertyMapFactory interface
• Include a constructor that takes ajava.util.Map argument
• Implement the createProperties methods returning the associated properties as a PropertyMap

The following is a simple example:

import java.util.Map;
import org.teatrove.trove.util.*;
public class MyPropertyMapFactory implements PropertyMapFactory {
    public MyPropertyMapFactory(Map config) {
        // do optional stuff with the config from properties.factory.init
    }

    public PropertyMap createProperties() {
        return createProperties(null);
    }

    public PropertyMap createProperties(PropertyChangeListener listener) {
        PropertyMap map = new PropertyMap();
        // do stuff
        return map;
    }
}

Note that the PropertyChangeListener property is currently not supported directly by the TeaServlet. TeaServlet provides the org.teatrove.trove.util.XMLPropertyMapFactory for parsing XML resources and org.teatrove.trove.util.SimplePropertyMapFactory for parsing enhanced property resources.

TeaServlet Configuration

The TeaServlet configuration contains the properties to setup the TeaServlet, the templates, the plugins, and the applications. See [INCLUDE LINK] for the various formats of this configuration file and [INCLUDE LINK] for the various options and properties.

Configuration Formats

TeaServlet supports two native configuration formats: XML and enhanced properties. The XML format is a standard XML file:

<teaservlet>
    <property>value</property>
    <section>
        <property>value</property>
    </section>
</teaservlet>

Alternatively, this could be rewritten in standard Java properties format via:

property=value
section.property=value

The enhanced properties format extends the Java properties format to support nesting sections and properties via:

property=value
section {
    property=value
}

All of these formats are equivalent. TeaServlet automatically selects the format based on the file extension. The enhanced properties follow all the rules for standard Java properties with the following additions:

• Values have trailing whitespace trimmed.
• Quotation marks (" or ') can be used to define keys and values that have embedded spaces.
• Quotation marks can also be used to define multi-line keys and values without having to use continuation characters.
• Properties may be nested using braces '{' and '}'.

TeaServlet Configuration Discovery

TeaServlet supports the ability to automatically discover and include the TeaServlet configuration within other libraries. TeaServlet will include the META-INF/teaservlet.xml or META-INF/teaservlet.properties configuration of any library in the class path. The configuration will not overwrite values defined in the application configuration file (ie: /WEB-INF/teaservlet.xml), with the exception of a few specific cases. The exceptions are that templates.path and template.imports will be aggregated together. The libraries are loaded and processed in a non-deterministic order. The automatic discovery allows libraries to automatically configure their plugins or applications rather than relying on the end user to manually configure. The TeaServlet uses this process internally for its Tea applications and Tea administration consoles.

TeaServlet Configuration Properties

The configuration file contains various sections as described below.

<teaservlet>
    <cluster>
        <!-- information to cluster multiple servers together -->
    </cluster>

    <templates>
        <!-- information on templates, locations, class files, etc -->
    </templates>

    <log>
        <!-- information on logging within TeaServlet -->
    </log>

    <admin>
        <!-- information on the administration console within TeaServlet -->
    </admin>

    <plugins>
        <!-- information on custom plugins -->
    </plugins>

    <applications>
        <!-- information on custom applications exposed to Tea -->
    </applications>
</teaservlet>

Clustering

TeaServlet supports clustering of multiple TeaServlet instances across multiple servers. Clustering is primarily used to allow templates to be compiled once across the cluster rather than individually on each server. The most common practice for clustering is one staging server with multiple user-facing servers. The staging server is used to initially test and validate on and then compile to the cluster of user-facing servers.

The clustering support in TeaServlet is based on multicast through the following configuration:

<teaservlet>
    <cluster>
        <name><!-- name of application cluster --></name>
        <localNet><!-- the local network address: ie: 10.1.1.0/21 --></localNet>
        <rmi.port><!-- the RMI port of the service --></rmi.port>
        <multicast>
            <port><!-- the multicast port to send/listen on --></port>
            <group><!-- the IP address of the multicast group --></group>
        </multicast>
    </cluster>
</teaservlet>

The multicast port and group should be the same for all instances in the cluster and different for services in different clusters. In general, all services in the cluster should use the same TeaServlet configuration.

Templates

TeaServlet supports precompiled templates, automatically compiled templates, and manually compiled templates. Precompiled templates are compiled at build time (using the Tea Compiler for Maven [INCLUDE LINK]) and included in the class path artifacts. Automatically compiled templates are similar to JSP and PHP in that they are compiled on demand and re-compiled when changes occur. Manually compiled templates require an administrator to selectively compile the templates through the Administration console. Both automatically and manually compiled templates may output the resulting class file to a working directory to avoid re-compiling on restarts.

The TeaServlet templates configuration also includes properties relevant to the Tea language including the automatic imports feature.

<teaservlet>
    <templates>
        <path><!-- semicolon delimited path to one or more template sources --></path>
        <classes><!-- filesystem path to where classes should be stored --></classes>
        <default><!-- default template when accessing a directory --></default>
        <preload><!-- whether templates should be compiled immediately on startup --></preload>
        <autocompile><!-- whether to automatically compile templates --></autocompile>
        <imports><!-- semicolon delimited packages to automatically import --></imports>
        <server><!-- properties relevant to the template server --></server>
    </templates>
</teaservlet>

path The path specifies one or more additional paths to search on for templates. This does not include precompiled templates that are available in the class path automatically. The path may be a path relative to the web application directory, a file-based path via the file: protocol, or a HTTP-based path via the http: protocol and the Template Server [INCLUDE LINK]. The template server is a more efficient web server for hosting templates remotely rather than using network shares. Multiple paths should be separated by semi-colons, such as /WEB-INF/templates;file://c:/templates;http://server/templates

classes This specifies an optional property of where to store generated class files. This only applies to templates compiled from the path property and not to precompiled templates. The path is a path relative to the file system. The generated classes will be stored in the given path. This allows the TeaServlet to reuse those class files on restarts without having to recompile. If not specified, then templates will be recompiled after restarts.

default This specifies the default template within the directory when a directory is specified as the path to the TeaServlet. By default, this is index.

preload The preload property specifies whether templates should be compiled on startup, rather than on demand. This is recommended for performance reasons and is true by default.

autocompile This autocompile property specifies whether templates should be automatically compiled on access or after changes rather than manually compiled. The default is false.

imports This specifies the list of packages to automatically import into Tea. Tea will make any classes within the given packages available to any template without fully-qualifying. The default is java.lang;java.util and multiple packages are separated by semi-colons. See [INCLUDE LINK] for more information.

server The server properties control various configuration options for handling the Template Server such as timeout.

Logging

The logging section control the TeaServlet logging. The properties specifies what portions of content to log: debug, info, warn, and error.

<teaservlet>
    <log>
        <enabled>true</enabled>
        <debug>false</debug>
        <info>true</info>
        <warn>true</warn>
        <error>true</error>
    </log>
</teaservlet>

Administration

The admin section controls the configuration of the Administration console. The key specifies the name of the query parameter to access the administration console and the value specifies the password.

<teaservlet>
    <admin>
        <key>admin</key>
        <value>password</value>
    </admin>
</teaservlet>

This particular example would require the following query parameter to access the console: http://server/context/system/console?admin=password

Plugins

The plugins section controls the inclusion of plugins [INCLUDE LINK FOR MORE INFO]. Each defined plugin should have its own section. The name of the section provides the name of the plugin within the TeaServlet plugin context. Each plugin definition should contain a class property and an optional init section.

<teaservlet>
    <plugins>
        <DataSourcePlugin>
            <class>com.mycompany.plugins.DataSourcePlugin</class>
            <init>
                <!-- data source properties -->
            </init>
        </DataSourcePlugin>
    </plugins>
</teaservlet>

See [INCLUDE LINK] for more information on plugins.

Applications

The applications section controls the inclusion of applications [INCLUDE LINK FOR MORE INFO]. Each defined application should have its own section. The name of the section provides the name of the application within the TeaServletapplication context. The name of the application is also the name that is used when fully-qualifying application-based context methods in Tea templates. Each application definition should contain a class property and an optional init section.

<teaservlet>
    <applications>
        <TestApplication>
            <class>com.mycompany.apps.TestApplication</class>
            <init>
                <!-- application properties -->
            </init>
        </TestApplication>
    </applications>
</teaservlet>

See [INCLUDE LINK] for more information on applications.

Table of Contents | Next - Plugins