John Topley’s Weblog

Just over a year ago I started to learn how to use the Jakarta Struts J2EE web application framework. During this journey it became apparent to me that there were some aspects of Struts that I found confusing at first, and that many other developers were going through the same difficulties. This series of articles is an attempt to address this problem.

There are now many good books on the framework and the online documentation is quite mature for an open-source project; but in spite of this, I have found myself having to refer to lots of resources to build a good understanding of Struts. Moreover, there are still some areas where the documentation is sparse. However, this occasional series isn't an attempt to provide a definitive source of documentation; I don't claim that my knowledge of Struts is at the level needed to be able to produce that. Rather, it's intended to allow newcomers to Struts to hit the ground running and to get a feel for what the framework is like and what it can and can't do.

The Struts example applications I have seen, I have found to be too trivial or too complex, with the complex ones having lots of external dependencies that have to be resolved before the example can even be compiled and run. With my example I'm attempting to hit a sweet spot between the two extremes, and I've deliberately created an application that has the minimum of external dependencies, so you should be able to actually run the code without too much difficulty! Everything you'll need is open-source and can be downloaded for free—one of the advantages of J2EE.

The example application that we're going to be building is an online discussion forum—which I've given the rather generic name of “Web Forum”. I've chosen an application of this type because it should be familiar and because you can create quite a lot of functionality without the complexity getting out of hand. It's fully functional, reasonably well-debugged and hopefully it should be fun learning how it all fits together.

It's important to state at the start that this code shouldn't be used as an example of a production-quality J2EE system. In particular, the exception handling is extremely and deliberately simplistic. This isn't a tutorial on persistence strategies, OO design or web application GUI design, it's simply a vehicle for learning Struts. There are doubtless aspects of what I've created that could be improved upon, but that's not important right now. So without further ado, let's crack on!

Ingredients

I'm going to start by talking about the ingredients you'll need to create the application. I developed it using Oracle JDeveloper 9.0.3 because that's the IDE I'm familiar with from my day job. You can use your tool of choice for writing the code. Note that throughout this series I'll be providing the source code as a download in both JDeveloper and non-JDeveloper form. The JDeveloper version will simply include JDeveloper's workspace and project files, so the project can be opened quickly and easily within that IDE.

This is a list of what else you will need:

• Jakarta Struts 1.1 (Web application framework)
• MySQL 4.0.18 or later (Database server)
• MySQL Connector/J 3.0 (JDBC driver for MySQL)
• A J2EE servlet container such as Apache Tomcat*

*I use the embedded OC4J server that comes with JDeveloper. I also use the MySQL Control Centre for creating the database and controlling the database server, although the MySQL command line can be used if preferred.

The Application

I'm now going to give a brief tour of the Web Forum's functionality. Some of this I'd thought about before I wrote a line of code, other aspects become apparent as I was building it. It helped that there are plently of existing forums to serve as inspiration!

Upon starting the application, the user is presented with a list of topics and information about each topic, such as the date and time it was posted, the number of replies and the topic's author. The most recent sixteen topics are displayed, ordered from the newest to the oldest:

The Topics screen. Click to enlarge.

At this point the user can click on a topic to view it and any follow-up replies:

The Topic screen. Click to enlarge.

The date and time of the post are displayed, as well as the author's name, the date they registered with the system and the number of posts they've made. The user can register if they are a new user, or log in if they are an existing user. A user must be logged in before they can create a new topic or a new reply. They can elect to automatically log in during registration or at the Login screen:

The Login screen. Click to enlarge.

The auto-log in feature uses a cookie that expires after thirty days. During registration they must provide a unique user name, their real name (or screen alias) and a password. All of these fields are mandatory apart from surname and they must confirm their chosen password by entering it twice:

The Registration screen. Click to enlarge.

After they have successfully registered they are taken back to the topics screen where they can create a new topic:

The New Topic screen. Click to enlarge.

Both the subject and message fields are mandatory. They are allowed to use the HTML <b>, <i> or <u> tags for basic text variations (bold, italic or underline) in the message field. Once they have created a new topic they are taken back to the Topics screen. The hyperlink to a topic contains an encoding of the number of replies to that topic, which ensures that the user can see which topics they have read, because the hyperlinks to those topics are displayed using the browser's visited link colour. Therefore, new replies to a topic cause that topic's hyperlink to be displayed using the browser's unvisited colour. Thanks to Joel Spolsky for this brilliantly simple idea.

When viewing a topic they can compose a new reply and again, the message field is mandatory and accepts basic formatting tags as before:

The New Reply screen. Click to enlarge.

Next Time

This article defined the boundaries within which this tutorial will operate and introduced the example application that we'll end up creating. Next time I'll introduce the data model and the class model that do the work behind the scenes, and we'll get practical and write the code to display the list of topics.