First Steps with Jakarta Struts

Just over a year ago, I started to learn how to use the Jakarta Struts J2EE Web application framework. During this journey, I realised that I found some aspects of Struts confusing at first, and that many other developers might well suffer the same difficulties. This article is an attempt to address that problem.

Many good books on the framework are now available, and the online documentation is quite mature for an open-source project; in spite of this, I have often had to refer to a wide variety of resources in order to build a good understanding of Struts. And there are still some areas in which the documentation is sparse.

However, this article isn't an attempt to provide a definitive source of documentation. Rather, it's intended to allow Struts newcomers to hit the ground running, to get a feel for what the framework is like, and understand what it can and can't do.

Of the Struts example applications I've seen, most have been either too trivial or too complex, the complex ones having lots of external dependencies that must be resolved before the example can even be compiled and run. In this tutorial, I'll attempt to hit a spot between these two extremes. 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 build 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 application becoming too complex. Our Web Forum is fully functional and reasonably well-debugged; hopefully, it should be fun to learn how it all fits together.

It's important to note that this code shouldn't be considered 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, object-oriented design or Web application GUI design; it's simply a vehicle for learning Struts. Undoubtedly, some aspects of what I've created here could be improved upon, but that's not important right now. Let's get started!

Ingredients

To start, let's talk about the ingredients you'll need to create the application. I developed the Web Forum using Oracle JDeveloper because I'm familiar with that IDE. You can use your Java tool of choice for writing the code.

Apart from the source code itself, here's a list of the other elements you'll need:

• Jakarta Struts 1.1 or later (Web application framework)
• MySQL 4.0.18 or later (Database server)
• MySQL Connector/J 3.0 (JDBC driver for MySQL)
• Apache Tomcat 5.0.28; or later (J2EE Web container)

I also used the MySQL Control Centre to create the database and control the database server, although the MySQL command line can be used if that's what you prefer. Note that, because this isn't a MySQL tutorial, some familiarity with MySQL is assumed. As a minimum, you'll need to know how to start and stop the database server, how to create a new database, and you'll need the ability to run a provided SQL script to create tables.

Source Code Downloads

These are the files we'll use through this tutorial.

• Download struts_webforum_jars.zip (855 KB)
• Download struts_webforum_src.zip (52 KB)
• Download struts_webforum_war.zip (1,122 KB)

To reduce the download sizes, I've split the Struts JAR files that go into WEB-INF/lib into a separate download. The pre-compiled WAR file is also available.

The Application

Let's take a brief tour of the Web Forum's functionality. I'd thought about some of this before I wrote a line of code, but other aspects became apparent as I was building the app. The fact that there are plenty of existing forums to serve as inspiration certainly helped!

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
• the topic's author

The 16 most recent topics are displayed, ordered from the newest to the oldest:

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

The date and time of the post are displayed, as well as the authors' names, the dates on which they registered with the system, and the number of posts they've made. The user can register if he or she is a new user, or log in if they're an existing user. A user must be logged in before he or she can create a new topic or a new reply. The user can elect to log in automatically during registration, or at the Login screen:

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

Upon successful registration, the user is taken back to the topics screen, on which he or she can create a new topic:

Both the subject and message fields are mandatory. Users are allowed to use the HTML <b>, <i> or <u> tags for basic text formatting (bold, italic or underline) within the message field. Once the user creates a new topic, he or she is taken back to the Topics screen.

The topic hyperlinks ensure that users can see which topics they've already read. The hyperlinks to topics that the user has already read are displayed using the browser's visited link colour. However, each topic link contains an encoding of the number of replies that have been made to that topic. 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, users can compose a new reply; again, the message field is mandatory and accepts basic formatting tags: