TeaServlet Lifecycle

Previous - Applications | Table of Contents | Next - Administration

TeaServlet supports both the GET and the POST operations in HTTP. Both operations are handled exactly the same to simplify the end templates and processing. All other operations are unhandled and not supported.

When a request is made, TeaServlet inspects the path excluding the context path and servlet path mapping, if any. The resulting path is used to lookup the associated Tea template. If the autocompile flag is enabled, TeaServlet will first check if a physical template exists for the given template by appending the path to each template path. If any are found, then it is checked for modifications and recompiled if necessary. Otherwise, the path is converted to a fully qualified class name and looked up in the class path. If the template class file cannot be found, then TeaServlet will attempt to resolve the path as a directory by appending the default template to the path (ie: index). If the template still cannot be found, then a 404 response is returned.

Tea compiles templates into class files with a known structure that allows them to be easily executed as well as providing information on the template parameters. For more information on the structure of the class files, see Tea Architecture. The main method in the class file is the execute method. The execute method takes one parameter for the execution context and then one parameter for each defined template parameter. For example, consider the following template definition:

<% template test(String name, Integer age) %>

The resulting method in the class file will be: Object execute(Object context, String name, Integer age). In order to invoke this method, TeaServlet must construct the necessary parameters.

The first parameter is the execution context. The execution context is a specially created class that contains an aggregation of the TeaServlet environment and all of the application context methods. TeaServlet dynamically creates this class at startup called the MergedContext by invoking the getContextType method of each application and introspecting all the public methods of the resulting type. The merged context then creates a method of the same signature as each application context method. When that method is invoked (ie: through a Tea template), the merged context delegates to the TeaServlet environment to invoke the actual method on the actual application context. Because this code is all dynamically created at startup, the actual class file is statically typed meaning there is no reflection or otherwise dynamic operations invoked. Combining this notion with the static typing of the Tea templates is what powers the low latency, high throughput performance of the TeaServlet.

The subsequent parameters of the execute method are from the template definition. The class file contains methods that return the metadata of the template including the template definition parameters, their types, and their names. This allows the TeaServlet to map the query parameters accordingly. For each template parameter, the TeaServlet checks to see if a query parameter exists of the same name. If the query parameter exist, TeaServlet automatically converts the value to the proper type, since all query parameters are strings. At this time, TeaServlet can only convert from strings to primitives or their corresponding object wrappers. All other objects must be specified as java.lang.String and manually converted by the template. Note that template parameters mapped as primitives that map to query parameters that do not exist will result in a ServletException being thrown.

TeaServlet can now invoke the associated execute method. It first instantiates the merged context with the current environment including the active request and response. For each application, it also invokes the getContext method passing in the active request and response. For stateless applications, this will usually return the singleton context. For stateful applications, this will usually create a new instance of the context. These contexts are then made available in the merged context so that the method delegates invokes the method on the associated context instance.

Once the TeaServlet invokes the execute method, the actual template code is invoked (in its compiled form). This includes invoking any of the application context methods, calling other templates, or printing text to the response. Once the template completes, any return value of the template is also output to the response. The response is then committed and flushed and control is returned to the web application to finish the request.

When a Tea template calls or invokes another template, it follows a similar process. The compiled class file invokes the calling template directly passing the execution context and required parameters. Substitution templates are slightly different. Substitution templates maintain a state so that they can process the included portion of the page accordingly. Because substitution templates maintain state, they are also instantiated per request, whereas most templates are static to ensure high throughput.

Previous - Applications | Table of Contents | Next - Administration