Use the Echo framework to build a functional Web-based
a practical application)
Chief Software Architect, NextApp,
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
You've got mail
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.
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 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:
- 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.
- Type ant and press Enter. Executing this command
invokes the default target of the build script to create a deployable
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
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
A quick tour of Echo
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
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.
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
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
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
derivative -- the
Application class -- for just such a
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.
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
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
Figure 1. The AuthenticatorScreen
When a user enters information into the fields of the
AuthenticatorScreen and clicks Log In, the server is
notified and the
actionPerformed() method is invoked. In this method, the
AuthenticatorScreen makes a call to the
connect() method, providing
the authentication information specified by the user as parameters.
connect() method invokes the JavaMail API to contact
the mail server and authenticate the user. If the user is granted access,
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 "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,
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
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
retrieves its data directly through the JavaMail API. The table also uses
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.
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
ComposeDialog class extends Echo's
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
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
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
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
MessagingExceptions to indicate an unexpected
condition. These are checked exceptions, thus our application must catch
them when they occur and recover appropriately.
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
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
ComposeDialog displays an error message
window describing the problem and then reverts to its previous state.
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
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
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
This reduces the amount of style-related code seen in the user-interface
components and centralizes all the look-and-feel information for easy
Where to go from
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
section below to find additional documentation, examples, and community
support and discussion areas.
- 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
- 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.
Tod Liebeck founded NextApp, Inc. in 2001 to pursue
advanced Web-based user interface technology. He currently serves as
the lead developer of the Echo Web application framework and Chief
Software Architect. Contact Tod at firstname.lastname@example.org.