Contents: You've got mail Setting up Core architecture Supporting architecture Resources About the author Rate this article Related content: Fundamentals of JavaMail API Working with the Echo Web framework, Part 1 Subscriptions: dW newsletters dW Subscription (CDs and downloads)

Tod Liebeck (mailto:tliebeck@nextapp.com?cc=&subject=Creating a practical application)
Chief Software Architect, NextApp, Inc.
9 September 2003

This two-part series provides an introduction to the Echo framework, an open source, Java technology-based platform for building Web applications that look and act like rich clients. Part 1 introduced the framework, examining how it works and in what applications it is best used. Part 2 takes you more in depth, building on your knowledge from Part 1 to develop a complete application using the Echo framework.

Now that you have the basics of the Echo framework well in hand, we're going to put your knowledge to practical use. In this article, we'll walk through the development of a real-world Echo application: a Web-based e-mail client.

You've got mail
To demonstrate a practical Echo application, we'll describe Echo WebMail, a Web-based e-mail application built on the Echo platform. We'll start with a simplified set of requirements to make the application work well as a tutorial. While this e-mail client might not be feature rich, it's designed on the presumption that more extensive capabilities will be added later. For the most part though, we'll stick to the basics: enabling users to send and receive e-mail.

Setting up
To make Echo WebMail work, the first thing you're going to need is a mail server. Echo WebMail uses SMTP to send mail, and can use either of the POP3 or IMAP protocols to receive it. It works just like a desktop-based e-mail client, so chances are fairly good that the mail server you're now using will work just fine.

Echo framework basics Part 1 of this series introduces you to the Echo framework and its capabilities.

Echo WebMail must be configured to check mail from your mail server before it is compiled. You configure the app by editing a properties file that is placed in the application's deployable Web archive (WAR) file at build time. This configuration file (Config.properties) is located in the Echo WebMail download in the src/app/echowebmail/ directory (see Resources). Directions for editing the file are included within it.

After you have configured the properties file to access your mail server, the next step is to compile the application. Echo WebMail includes an Ant build file that creates a ready-to-deploy Web archive. To start the compilation process, follow these steps:

1. Open a terminal (or command prompt) window and change the working directory to the root directory of the Echo WebMail package. This directory should contain the file build.xml.
   
   
2. Type ant and press Enter. Executing this command invokes the default target of the build script to create a deployable Web application.

If everything works as advertised, Ant informs you that the build was successful, and you'll have a shiny new application sitting in the war subdirectory.

The Web archive you just built now needs to be deployed to your servlet container. If you're using Tomcat, simply copy the EchoWebMail.war file from the war subdirectory of the Echo WebMail package into the webapps subdirectory of Tomcat, then (re)start Tomcat. You should then be able to access the application by visiting the /EchoWebMail URI on the host (and port) on which the servlet container is operating. If you have a default Tomcat install running on your local machine, the full URI is http://localhost:8080/EchoWebMail.

A quick tour of Echo WebMail
When you first visit the application, an authenticator screen displays. On this screen, enter your e-mail user name (just the part before the "@" sign in your address) and password. There's also an option to choose your language. Once you enter this information, click Log In to connect to the mail server. (Note: If your configuration is not working properly, an error message pops up in a separate window explaining that you have a problem.)

Echo WebMail then fills your browser's window with its ContainerPane-derived MailScreen object. This screen is divided into three regions, with a toolbar at the top, a list of messages in the middle, and a message-viewing pane (initially empty) at the bottom. Using this screen is pretty straightforward. Clicking a message highlights it and displays its content in the message viewing pane below. The arrows in the toolbar are used to navigate among pages of messages, and the Exit button returns you to the authenticator screen. You can send e-mail by clicking either Compose or Reply to open a compose dialog window.

That's about all there is to it. The application doesn't support viewing alternate mailboxes, deleting messages, displaying HTML e-mail, or uploading and downloading attachments, but the core functionality of an e-mail client is very much available.

Core architecture
When broken down into its fundamental parts, there isn't a whole lot to an e-mail program. As you can see from our brief tour of Echo WebMail, the application pretty much consists of a log-in screen, a view-your-mailbox screen, and a dialog box used to send messages. Hence, one of the primary reasons for using this application as an example is its simplicity.

Conversing with the mail server
To send and receive messages, Echo WebMail uses the JavaMail API. The JavaMail-based operations performed in the Echo WebMail application are fairly straightforward, as the program only makes use of the more basic capabilities of the API. See the Resources section for more information about JavaMail and a link to an online tutorial.

The application class
In a reasonably sophisticated application, the EchoInstance class tends to take on a more significant role than merely laying out the initial state of the user interface. The fundamental purpose of an EchoInstance object is to represent the overall state of a single user instance of an application. It therefore makes a great deal of sense for our subclass to take advantage of this purpose in an application-specific fashion.

In the case of Echo WebMail, we use our EchoInstance derivative -- the Application class -- for just such a purpose. The Application object is responsible for managing the overall state of the Web application. It performs functions like connecting and disconnecting the user instance to and from the mail server, and provides methods for changing the content of the main window and displaying error dialogs.

Authenticating users
The first thing a user sees when visiting Echo WebMail is the authenticator screen -- a component coincidentally named AuthenticatorScreen, shown in Figure 1. It is derived from the Echo ContentPane class, but at construction it sets itself up to contain input fields for user name, password entry, and language selection. It also creates a Log In button, which it adds itself to as an ActionListener.

Figure 1. The AuthenticatorScreen component

When a user enters information into the fields of the AuthenticatorScreen and clicks Log In, the server is notified and the AuthenticatorScreen's actionPerformed() method is invoked. In this method, the AuthenticatorScreen makes a call to the Application class's connect() method, providing the authentication information specified by the user as parameters.

The connect() method invokes the JavaMail API to contact the mail server and authenticate the user. If the user is granted access, the connect() method updates the overall state of the application to display a MailScreen pane component, which enables the user to browse received mail. If authentication fails, the method returns a value of false, indicating an authentication issue. In such a case, the AuthenticatorScreen then raises an error dialog window indicating the problem to the user and returns to its previous state of requesting login information.

The MailScreen object
The "main event" of the application is the MailScreen object and its supporting classes. MailScreen provides a multiple-pane interface that enables a user to simultaneously browse a list of messages and see a complete view of a single message.

The screen, shown in Figure 2, is composed of three ContentPanes: a toolbar, ListPane, and MessagePane. The toolbar is created by MailScreen itself, and consists of buttons to navigate between pages of messages, as well as buttons to compose a message, reply to the selected message, and log out of the application.

Figure 2. The MailScreen

The ListPane, which occupies the middle region of the screen, provides a multi-paged list of messages that it pulls from the user's inbox. The ListPane component extends Echo's ContentPane class, but its real magic is built around a Table component embedded inside. This embedded Table features a custom TableModel that retrieves its data directly through the JavaMail API. The table also uses its own TableCellRenderer to render each table cell as a button. The renderer adds itself as a listener to ActionEvents from these buttons. When a user clicks the buttons, it re-renders the message as selected and informs the MessagePane that it should display the selected message. The renderer also adds some visual cues to its output by alternating the background colors of each row in the table for clarity and highlighting the currently selected message in a brighter color.

Sending messages
When a user clicks Compose or Reply on the toolbar of the MailScreen, the application opens a new window -- a ComposeDialog -- in which the user may compose a message. The window contains fields to set the recipients, subject, and body of the message, in addition to a toolbar with buttons to send or discard the message.

The ComposeDialog class extends Echo's Window component. On initialization, it configures its layout by setting its root content as a ContainerPane that contains two ContentPanes. The upper pane provides the toolbar, while the lower pane provides the message composition area.

The functionality to send the e-mail message lives inside the sendMessage() method of the ComposeDialog class, shown in Figure 3, and is invoked when the user clicks Send. The sendMessage() method invokes the JavaMail API in an attempt to send the message, then reports back any issues by opening an error dialog, if necessary.

Figure 3. A ComposeDialog class

Supporting architecture
There's more to an Echo user-interface than just the visible component objects. So far, we've discussed the major architecture of the Echo WebMail application; now we'll take a look at the details.

Exception handling
The primary problem sources for our Web mail application are likely to be based on invalid user input or issues communicating with the mail server. Most calls into the JavaMail API, for example, have the possibility of raising MessagingExceptions to indicate an unexpected condition. These are checked exceptions, thus our application must catch them when they occur and recover appropriately.

The Application class provides a means of handling the more unexpected exceptions, in the form of its processFatalException() method. When this method is invoked, an error dialog window is raised that describes the error that has occurred and then displays the AuthenticatorScreen in the main window.

Less catastrophic exceptions are handled at the lower levels of the application. For instance, the ComposeDialog may encounter an exception from the JavaMail API when attempting to send a message in which the user has specified an invalid recipient e-mail address. In such circumstances, the ComposeDialog displays an error message window describing the problem and then reverts to its previous state.

Localizing an application
Localizing an Echo application is largely accomplished through the same means as localizing a Java desktop application written using Swing. Each EchoInstance, and every Component within an EchoInstance, has a locale property. When locale information is requested from a component, the hierarchy is searched from the component all the way up to the EchoInstance, and the first found locale is returned. In most cases, however, only the EchoInstance itself has its locale property set.

When a user logs in to the Echo WebMail application, the locale of the EchoInstance is set based on the user's language selection. This means that invoking getLocale() on any component of the application results in the user's specified locale being returned.

All messages in Echo WebMail have been externalized into localized resource bundles, which makes adding support for new languages as easy as creating additional resource bundles. To gain quick access to such resources, we've created a Messages class to deal with all things localizable. The class contains methods for retrieving strings, formatting data, and retrieving properly localized dates.

Look and feel resources
All look-and-feel resources used by Echo WebMail are housed in a single LFResource class. The class is not intended to be instantiated, but rather contains static constants for the various styles and images used within the application.

Wherever possible, stylistic attributes have been grouped into Style objects and moved to the LFResource class. This reduces the amount of style-related code seen in the user-interface components and centralizes all the look-and-feel information for easy modification.

Where to go from here
With Echo, you can quickly build Web-based applications that work like rich clients using a component- and event-driven architecture. You've now seen the basic elements required to put together a complete application using this technology. From here, you're on your way to creating applications of your own. For more help, take a look at the Resources section below to find additional documentation, examples, and community support and discussion areas.

Resources

• The Echo home page provides useful resources for Echo developers.
  
  
• Download the Echo Web application framework. This page provides links to download the latest versions of the Echo libraries. You'll need them to create Echo applications of your own.
  
  
• Download the Echo WebMail sample application (j-echo.zip). This download contains the source code of the sample application discussed in this article.
  
  
• Learn more about JavaMail in the tutorial "Fundamentals of JavaMail API" (developerWorks, August 2001).
  
  
• Take an in-depth look at building Echo applications in the Echo online tutorial.
  
  
• The Echo High-Level Technical Overview provides a detailed explanation of the how the inner architecture of Echo works.
  
  
• Visit the demo applications Web page to see online examples of Echo-based applications, including the Echo WebMail demo.
  
  
• The Apache Ant home page provides information about Ant and the latest versions for download. Ant is used to build the sample applications used in this article.
  
  
• The Apache Tomcat home page provides information about the Tomcat servlet container and the latest versions for download.
  
  
• Find hundreds of Java technology-related resources in the developerWorks Java technology zone.
  
  

What do you think of this document? Killer! (5) Good stuff (4) So-so; not bad (3) Needs work (2) Lame! (1) Comments?

developerWorks > Java technology | Web architecture