14.4 Tea Administration

Java Servlet Programming, 2nd Edition > 14. The Tea Framework > 14.4 Tea Administration

< BACK

CONTINUE >

The TeaServlet framework provides a centralized administration web page (written in Tea of course) with which a site administrator can manage all the Tea templates and supporting application classes. The administration screen makes it possible to view the currently loaded templates, view the currently enabled applications, and peruse the functions made available by those applications in a Javadoc-like style. It also provides access to runtime logs for the templates, letting the administrator view all logs or be more selective based on template and log level (debug, info, warn, or error). The administration screen also provides a mechanism for controlled template reloading, as we'll talk about later in detail. A screen shot of the Templates page is shown in Figure 14-1.

Figure 14-1. Administering the currently loaded templates

To run the TeaServlet administration application we must first flesh out the TeaServlet.properties file. An example configuration file is shown in Example 14-4.

Example 14-4. A Starter TeaServlet.properties File

# TeaServlet.properties # Specify the location of Tea templates (the .tea files) template.path = /tomcat/webapps/teatime/WEB-INF/templates # Specify an optional path for where the system will write compiled  # templates, as .class files template.classes = /tomcat/webapps/teatime/WEB-INF/templateClasses # Specify an optional default template to load if none is given template.default = Index # Specify the supporting applications to load into the TeaServlet system applications {     "System" {         # The SystemApplication provides TeaServlet administration support         class = com.go.teaservlet.AdminApplication         init {             # The security key for the Admin page             admin.key = admin             admin.value = true         }     }     "Other" {         class = MoreOnApplicationsLater     } } # Specify what application messages are printed to the log file log.debug = true log.info = true log.warn = true log.error = true

The TeaServlet.properties file configures the TeaServlet system much like the web.xml file configures a web application. This file tells the TeaServlet where to find template files, where to place compiled template classes so they can be saved between server restarts, which applications should be loaded to support templates, and what level of log messages should be written by default. Each application must be registered in TeaServlet.properties with a specified class file and optionally specified init parameter name/value pairs.

The structure of TeaServlet.properties operates like a traditional java.util.Properties file with several important enhancements: ordering of elements is preserved, quotation marks (single or double) can be used to define keys that have embedded spaces, and properties may be nested using curly braces. Example 14-4 could be written using a normal Java properties file using the longhand shown in the following code (although if read by the java.util.Properties class the order between elements would be lost). The file could have been written using XML, although for simple uses such as this, XML may be buzzword-compliant overkill:

template.path=/tomcat/webapps/teatime/WEB-INF/templates template.classes=/tomcat/webapps/teatime/WEB-INF/templatesClasses applications.System.class=com.go.teaservlet.AdminApplication applications.System.init.admin.key=admin applications.System.init.admin.value=true applications.Other.class=MoreOnApplicationsLater log.debug=true log.info=true log.warn=true log.error=true

After editing the TeaServlet.properties file and restarting your server, the system is ready for administration. The default location for the admin application (assuming it's installed in the /teatime context) is http://localhost:8080/teatime/tea/system/teaservlet/Admin?admin=true. The ?admin=true operates as a primitive security precaution; the name and value must match the admin.key/admin.value from the TeaServlet.properties file. There's really nothing significant an outsider could gain by accessing the admin pages, but having a wide-open front door isn't wise either, so this provides a primitive lock. The odds are good the open source community will quickly improve this security mechanism.

The most common use of the admin application is the reloading of template files. Templates do not automatically reload on access as do JSP pages. Changes to templates aren't seen until the Reload Changes button is clicked on the Templates admin screen. Compiling templates only on demand is more efficient than performing a file timestamp check during a request and also allows for a more explicit "publish" step to occur on an active site. The admin application rejects all changes if a template fails to compile, allowing the previous version to persist so clients absolutely cannot ever see a compile error. All errors occurring during the compile are listed in the administration application, as shown in Figure 14-2.

Figure 14-2. Comprehensive and precise compile error messages

Notice how the error location and description are perfectly precise. The TeaServlet can do this because Tea templates compile directly to Java bytecode! There's no interim .java file created and no Java compiler needed. Compiling templates directly to bytecode takes advantage of JIT and HotSpot technologies for maximizing performance, but unlike JSP pages, the compiler works directly on source written by the human and can better diagnose errors without the intermediary file adding a level of indirection. Also, Tea doesn't require bundling a Java compiler with the web server as is needed with JSP, a requirement that can be fraught with licensing difficulties. Tea can precompile templates as well, allowing the distribution of templates without the template source.

Compiled Templates: a Business Opportunity

The ability to distribute precompiled Tea templates opens up an interesting new business model. A vendor creating a web application using Tea has the option to sell the web application without giving away the original source code for the templates. All that's needed is the Tea library, which is portable across servers and can ship with the application. Being able to ship product without shipping code may encourage some vendors to produce new web applications for sale.

Note that JSP also supports precompiling pages. Unfortunately, the bytecode generated by JSP often has dependencies on container-specific classes and the generated class must follow a container-specific name-mangling convention (see Example 18-2 from Chapter 18). This tends to tie the precompiled JSPs to a particular container.

Tea also handles runtime errors elegantly. Exceptions thrown from within Tea contain stack traces that include Tea template line numbers, like this:

2000/07/10 19:29:12.105 PDT> java.lang.NullPointerException:      at com.go.teaservlet.template.SimplePage.execute(SimplePage.tea:5)          at java.lang.reflect.Method.invoke(Native Method)     at com.go.tea.runtime.TemplateLoader$TemplateImpl.execute(TemplateLoader.java, Compiled Code)     at com.go.teaservlet.TeaServlet.processTemplate(TeaServlet.java, Compiled Code)     at com.go.teaservlet.TeaServlet.doGet(TeaServlet.java:238)     <etc>

Messages such as this can be viewed using the TeaServlet administration application. When they occur the client by default receives a 500 status code error page, intentionally without a stack trace for security reasons.

Tea also has an "exception guardian" feature. This feature enables Tea to continue to process the page while logging the exception. Tea renders whatever parts of the page it can while omitting the small section that is affected by the exception. For many sites, a page that is missing a small section is better than a server error being returned to the user.

< BACK

CONTINUE >