J2EE(tm) BluePrints: Questions and Answers:

Questions and Answers - The Sample Application

How does the Java Pet Store templating mechanism work?

Where and how should configuration information for a web application be stored?

How does Internationalization work in the Java Pet Store?

1. How does the Java Pet Store templating mechanism work?

Java Pet Store version 1.1.1 has a somewhat more configurable, and higher-performance, templating mechanism than does 1.0.1 (which is the version in the book). Instead of templating tag-based pages created with JavaServer Pages^TM technology (JSP^TM pages), the templates are now kept in XML files. While the new format is almost identical to the old, this change has greatly improved performance.

The new XML-based templating solution provides many benefits. XML is a useful, consistent way of representing application parameters. The XML format is easy to use for both presentation specialsts and third-party tools. The fact that XML is standardized means we can use off-the-shelf software to handle all the details of parsing and writing our screen definitions, configuration files, and other forms of structured data. Finally, XML can be validated against a DTD (Document Type Definition), so errors relating to ill-formed input can be handled by the parser, instead of in the application code.

The templating system is controlled by three files:

The template file (template.jsp), which defines the basic layout of all of the pages generated from the template
The request mappings file (requestmappings.xml), which maps virtual URLs to screen names (or request handler classes). There is one request mappings file in the Pet Store application.
The screen definitions file (screendefinitions.xml), which defines the parameters for each screen. There is one screen definitions file per supported language.

The main controller servlet MainServlet (javadoc, source) receives incoming HTTP requests. MainServlet matches the incoming url to the URLs defined in the request mappings file, obtaining a screen name. The template parameters corresponding to the screen name are retrieved from the screen definitions file, and the template is then served using those parameters. (Of course, MainServlet doesn't do all of this itself: most of the work is delegated to other classes that specialize in screen flow management, template instantiation, and so on.)

The XML files in the templating system are parsed by a standard XML parser, created using the JAXP (Java API for XML Parsers) optional package.

This process is easier to understand by showing portions of the actual files themselves. Say, for example, that MainServlet receives a request for the URL http://javapetstore.com/main, and that MainServlet's URL is http://javapetstore.com. MainServlet finds find the following line in the request mappings file:

<url-mapping url="/main" screen="MAIN"/>

indicating that the screen called MAIN is being requested by the client. The corresponding entry in the screen definitions file is:

<screen>
    <screen-name>MAIN</screen-name>
    <parameter key="HtmlTitle"
                  value="Welcome to Java Pet Store Demo"
                  direct="true"/>
    <parameter key="HtmlBanner"
                  value="/banner.jsp"
                  direct="false"/>
    <parameter key="HtmlBody"
                  value="/index.jsp"
                  direct="false"/>
    <parameter key="HtmlFooter"
                  value="/footer.jsp"
                  direct="false"/>
</screen>

The block of XML above, from the screen definitions file, defines values for the template parameters that will be substituted in the template. (Notice that the lookup of the screen name


MAIN

is case-sensitive.)

Now imagine that the template file template.jsp looks like this (which it does):

<%@ taglib uri="/WEB-INF/tlds/taglib.tld" prefix="j2ee"%>
<html>
  <head>
    <title>
      <j2ee:insert parameter="HtmlTitle"/>
    </title>
  </head>
  <body bgcolor="white">
    <j2ee:insert parameter="HtmlBanner" />
    <table height="85%" width="100%" cellspacing="0"
           border="0">
     <tr>
     <td valign="top">
        <j2ee:insert parameter="HtmlBody"/>
       </td>
     </tr>
     <tr>
      <td valign="bottom">
        <j2ee:insert parameter="HtmlFooter"/>
      </td>
     </tr>
    </table>
  </body>
</html>

The template is served as a JSP page, and the inclusion of the dynamic content occurs because the JSP engine calls the custom tag <j2ee:insert> each time it occurs. How does MainServlet create an HTML web page from template.jsp? MainServlet.service() identifies the screen to display, and places that screen's data in the session object. It then "forwards" the request to template.jsp; that is, it instructs the web container to evaluate template.jsp. Since template.jsp contains references to the custom tag <j2ee:insert>, the custom tag InsertTag (javadoc, source) is called back each time the custom tag is encountered.

Remember that the screen's data (its parameter values) were stored in the session by MainServlet. While template.jsp is being evaluated, InsertTag is called back several times, with different values for its parameter attribute. InsertTag looks in the screen data under the name parameter, extracts the name of the file to insert, and either includes or evaluates the file associated with that parameter. While the description is a bit convoluted, the operation is fairly straightforward. Look at the source code for MainServlet and InsertTag (linked above) to better understand how template evaluation works.

Note that MainServlet also handles the internationalization of its content by selecting the appropriate template to be evaluated, based on user preferences. Read more on how internationalization works on our Internationalization page.

The benefits of a template mechanism are discussed in the Web Tier section.

2. Where and how should configuration information for a web application be stored?

Usually, configuration information belongs in the application deployment descriptor, web.xml, packaged in the WEB-INF directory of the .war archive.

But in some situations, you may want to place configuation information for a web application in some place other than in the deployment descriptor. For example, consider an workflow enterprise bean that requires a complex XML configuration that can't be placed in a deployment descriptor. Where does such configuration information belong?

We recommend storing web component configuration files (including web.xml) in the application's WEB-INF/ directory. This directory is visible to your application code, but not to browser clients, so there is no way users can directly read the data in any file in this directory.

We also recommend that configuration files be in XML format, and that you access your application configuration information by retrieving a resource URL using javax.servlet.ServletContext .getResource() method. (A servlet's method getServletContext() will return an object that implements ServletContext.)

Here is some sample code that gets a configuration file from the WEB-INF/ directory and parses it as XML.

URL myURL = null;
try {
    myURL = context.getResource("/WEB-INF/mysettings.xml");
} catch (java.net.MalformedURLException ex) {
    System.out.println("Malformed URL exception: " + ex);
}

// Load the contents of the URL as a DOM

try  {
    InputSource xmlInp = new InputSource(myURL.openStream());
    DocumentBuilderFactory docBuilderFactory = DocumentBuilderFactory.newInstance();
    DocumentBuilder parser = docBuilderFactory.newDocumentBuilder();
    doc = parser.parse(xmlInp);

    Element root = doc.getDocumentElement();
    root.normalize();

    // Do whatever you want to with the DOM tree...

} catch (Exception e) {
  ...
}

The example above uses the DOM interface to an XML document, but any XML API (SAX, JDOM, etc.) will do, depending on your application requirements.

3. How does Internationalization work in the Java Pet Store?

The Java Pet Store manages internationalization by selecting a locale-specific screen definition based on preferred user locale. For each supported language, a different screen definitions file specifies the content for that language. (For a description of the Java Pet Store templating system, see Templates.) Applications may be partially internationalized by simply translating only some of the elements in the screen definitions file.

The screen definition file encoding should support the language the file represents. The Java Pet Store sample application encodes the screen definitions in ISO 8859-1 (Latin 1), and the Japanese screen definitions are encoded in ISO 10646-1 (Unicode). Users can change the presentation language of the Java Pet Store at runtime. The user's language preference is stored in the user's session object as an instance of class


Locale

Since the screen definitions file specifies the template file to be used for the screens, screen layout may also customized for each locale. For example, a navigation bar on the right side of the page may be more appropriate for languages such as Hebrew and Arabic, which read right-to-left.

CONTENTS | PREV | NEXT | INDEX