world-calendar.com - Technical Details

Introduction
The Big Picture
Development Environment
Design Overview
Servlet Class Diagram
Internationalization Issues

Introduction
This documentation is to document and share the experience and design decision and issues that went into developing world-calendar.com, it's by no mean to say this is the right way of doing it.
world-calendar.com is a web-based perpetual calendar. It contains holidays of over 75 countries and holidays of four religions: Christian, Islamic, Jewish, and Orthodox. In addition, it includes four other calendrical systems, Chinese, Japanese, Hebrew, and Islamic, all of which are relative to Gregorian. The web site can be viewed in five additional languages besides English, which are German, French, Japanese, Traditional and Simplified Chinese.
The Big Picture
world-calendar.com is developed using the Java servlet framework and Java Server Page (JSP) to create dynamic content using HTML and java code on the server.
The following diagram shows the sequence of events that has to take place when a user requests http://www.world-calendar.com/index.jsp for the server to return the response.
The diagram also shows the relationship amongs the different players on both the client and the server sides to complete a request and a response. On the client side, there is only one player, the browser. On the server side, it gets a little complicated and includes serveral players: the HTTP server (Apache), JSP/servlet engine (Tomcat), the JSP pages, and the Calendar servlet.
1. User requests http://world-calendar.com/index.jsp. The browser sents the request to the HTTP server (Apache Web Server) in world-calendar.com.
2. Apache server sees that the .jsp extension in the URL and recognizes it must be handled by a JSP engine and forwards it to the Tomcat JSP engine.
3. The Tomcat JSP engine invokes the requested page, index.jsp, which might have already been compiled into a servlet and cached in the memory if the page has previously been requested.
4. index.jsp contains a jsp action element "jsp:forward" to forward the request to Calendar servlet.
5. The Calendar servlet processes the request to figure out which calendar system, what holidays and in which language that the user requests. It then dispatches cal.jsp.
6. cal.jsp generates a response in html format.
7. The Tomcat JSP engine sends the response to Apache server.
8. The Apache server sends the response to the browser, which completes the request.

Development Environment

world-calendar.com is developed on Redhat Linux 6.2, using IBM's JDK 1.3. and Jakarta Tomcat 3.1 for Java Server Page (JSP). Setting up the development environment is a rather complex task. To see the details, please go to: install-apache-tomcat.txt

Design Overview

Why Java Servlet and JSP
JSP provides a good separation between the client and the server. JSP encompasses all the GUI elements such as HTML, java beans, java and Javascript.
JSP pages are compiled once and kept in the cache for subsequent requests for better performance.
JSP and Servlet Relationship
The diagram below shows the relationship between the JSP pages and the Java servlet.
index.jsp invokes the servlet Cal, using JSP's 'jsp:forward' action. The servlet processes the request and then displays the calendar by dispatching cal.jsp. To dispatch a jsp page, use Java's RequestDispatcher, which can be obtained from ServletContext.
The jsp pages in bold indicate the pages that would change if a user selected a yearly holiday view. All other jsp pages remained unchanged and can be reused. See the diagram below.
In addition, all jsp pages are compiled once and cached on the server, which will improve performance by not having to compile every time when a user requests a page.

Servlet Class Diagram

Top Level Class Diagram
Below is the class diagram for the servlet, Cal.java. It inherits from HttpServlet in the javax package. It contains classes for different calendar systems. WorldHolidays is for managing the world holidays, and serveral resource classes for managing resource bundles.
WorldHolidays Class Diagram

Below is the class diagram for WorldHoliday, which is used to managing world holidays. It contains classes for the holidays, one for each country, and one for each religion, that are supported.

Internationalization Issues

Language Selection and Detection
Since world-calendar.com is a multilingual web site, it provides ways for user to select a preferred language. First, it shows all the languages that're supported across the top of the page to allow user to select it at any time. Second, it automatically detects the user's preferred language by examining the value of "Accepted-Language" setting from the HTTP header. The "Accept-Language" string may look something like "en; qvalue=0.91", inciating the user prefers English language, or it may look like "zh-TW; qvalue=0.91", indicating the user prefers Traditional Chinese.
Resource Isolation
One of the nicest things about using Java and JSP is that all locale sensitive GUI elements such as messages, screen geometry, button labels and menus can be isolated in the resource files. This makes localization much easier. The translators need only to translate the resource files, instead of, for example, a bunch of HTML files.
The Java resource file contains pairs of tag and value, e.g., jan=January, which is much easier to translate than with html files, with lots of html tags.
During servlet initialization, these resources are loaded into memory and indexed by language. When the browser requests a page, depending on user's language preference, the appropriate resource is retrieved and displayed.
Following is a diagram showing the three Resource classes, all of which use the PropertyResourceBundle class. Each one of them is responsible for loading and providing the localized resource for the languages supported. During run time, the JSP page calls the APIs provided by these classes to retrieve the localized resource for the language the current user prefers.
Character Set and Encoding
Since world-calendar.com supports two Western European and two Asian languages, it has to uses various encodings to display different character sets. For German and French, it use ISO8859-1 encoding. For Japanese, it uses Shift-JIS since most browsers supports it. For Chinese, it uses Big5 for Traditional and GBK for Simplified. The encoding is specified in the HTTP header, using Response class's setContentType method. For example, the Java code
"response.setContentType ("text/html; charset=Big5");" is used to set encoding for Traditional Chinese.
Because the older browsers may not support Unicode and most users might not have Unicode fonts installed, therefore, it is decided not to use Unicode encoding.

Table of Contents