TDDI48 Project Part 0: Introduction to the Message Forum Project

Written by Jonas Kvarnström. Please report any bugs, inconsistencies or vague requirements as soon as possible.

Recent changes and updates

None.

The Message Forum Project

The message forum project will be implemented in the following steps.

Note that although the project instructions provide a minimum requirement, you are strongly encouraged to add your own features to the forum and to explore other aspects of web-based programming. You are also encouraged to suggest new possible extensions to the course leader. Please include the course code "TDDI48" in the subject.

Before you get started with the project, please continue reading the remainder of this document. It contains important information about the entire project, and much of this information will not be repeated in the other parts of the project description!

The Programming Environment

We strongly recommend that you use the IntelliJ IDEA integrated development environment, which provides code support, code navigation, and many useful code analysis functions for Java code as well as JSP code and Javascript.

If you decide to use another development environment, you will still have to hand in your project in the shape of a fully functional IDEA project! We will be using built-in IDEA functionality together with a number of plugins to enable us to navigate through your code more easily as well as to help assess the quality of your code.

If you want to work at home, you will have to set up the following software by yourself:

If you don't know how to set up your own lab environment, please use the lab environment we have provided for you.

Asking for Help

If you need to ask for help, you should first check the list of common problems. This list is updated during the course, so even if your problem was not listed a couple of hours ago it may be listed now.

If you want to ask for help by e-mail, please include the course code "TDDI48" in the subject.

If your problem isn't listed and there is no lab assistant available, you can still ask for help by e-mail. In that case, please make sure that you give us all the information you can find about the problem:

Externally Visible Requirements

There are a number of requirements that you should consider throughout the project. We will begin with requirements affecting the user-visible part of the application.

Please read this section carefully.

Requirements: Robustness, Security and Error Handling

Robustness and security is very important for any web-based application. Any potential problem in a high-profile application will almost certainly be exploited by those attempting to gain access to your computer or simply crash the application to make it inaccessible to others. Therefore, your guest book should be:

We do not expect a "mission-critical enterprise-class" application (to use a few buzzwords), but the server definitely should not crash because the database file is missing or a user's name is too long.

One particularly important clue: All input from the user must be validated, or you must use techniques that ensure that arbitrary inputs can be accepted without security risks. This is especially true for input that will be used as part of an SQL query, such as user names that will be used to retrieve account information for a particular user. You do not want your users to be able to enter arbitrary strings that are inserted into SQL queries.

You must also take care of all exceptions that can occur in any Java code that you write, and you must not use a simple catch-all clause such as "catch (final Exception e)" — if a method call can throw more than one exception, you must explicitly handle each different exception that can be thrown.

Naturally this does not mean you have to handle an exception exactly where it occurs: In many cases, it is better to allow a method to pass on an exception to its caller, which may be better equipped to handle the exception. Examples of this were given during the lectures.

You must always deal with exceptions and other problems as well as you can, and attempt to recover gracefully. For example, the server you will write can't simply exit when there is an I/O exception — it must be robust.

If you want to print an exception, don't use System.out.println(ex), since it doesn't print the stack trace. Use the ex.printStackTrace() method instead — that way, you can see exactly where the exception occurred (class, method and line number), which method called that method, and so on.

    try {
        whatever();
    } catch (final IOException e) {
        e.printStackTrace();
        doSomethingAboutIt();
    }

Requirements: Correct HTML and CSS

Just like the Java code you write, the HTML and CSS you write and create should be readable and follow the standards. You must also write your HTML documents manually, to ensure that you actually understand how HTML works. In addition to the course slides, there are HTML tutorials available on the web. You are also allowed to use an HTML editor such as Mozilla Composer as a "helping hand": You must not use it to design entire documents, but you can use it to test various layouts and to find out how the resulting HTML code would look, as long as you use this knowledge to write your own HTML document rather than just cutting and pasting HTML tags directly.

For HTML, you should use HTML 4.01 transitional or strict, according to the standard. But don't worry: You don't have to read the entire standard. Instead, try to follow the instructions given during the markup lecture, and verify that the document is syntactically correct by including a suitable DOCTYPE and using the HTML validator.

You should use one of the following two DOCTYPEs:

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
    "http://www.w3.org/TR/html4/strict.dtd">
    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">

For simplicity, you can add a link to the HTML validator on all static web pages. Create a link to http://validator.w3.org/check/referer.

Regardless of the DOCTYPE you use, you should use CSS for all formatting, such as font styles and sizes, colors, and so on. You should create new CSS classes for different kinds of logical elements whenever this seems reasonable. For forum messages, for example, you may want to specify separate classes for subjects, authors, and actual messages.

CSS should be validated using the CSS validator.

CSS code should be commented.

Requirements: Design and Usability

Though this course isn't mainly about design and making "pretty" web pages, you should nevertheless spend some effort creating a clean, professional interface. This involves using readable fonts and colors, only using highlighting for important items, creating a layout that makes good use of the space that is available without being too cluttered with information, and making sure that the functionality and information users need can be found where users expect it to be found.

Obvious usability and design problems: Do not use purple text on a pink background throughout your pages. If you need 15 action buttons or links, do not place them on their own rows, widely spaced, and then allocate 10 percent of the screen area to useful information. Do not use gigantic fonts for headers and microscopic fonts for the actual text you want to read.

Less obvious usability and design problems: People expect links to be blue, and people expect blue things to be links. Do not change the standard link color (blue) unless you have a very good reason for doing so, and do not use blue text for any other purpose than links to other information. If you want to use dark backgrounds, please also allow the use of an alternate CSS stylesheet with a light background – most people prefer this.

Text entry: Whenever a user has to write something, you should make sure that text fields and text areas are large enough. It is surprising how many students design web forums where the size of the text area used for writing forum messages is 40x5 characters. Users expect at least the standard 80 characters of width, and if you want to actually use the message forum for some reasonable purpose, you will occasionally write messages longer than 5 lines. 80x20 might be a better compromise.

Navigation: Being able to move around in a natural manner is very important. If you just replied to a message in a certain message forum, you do not expect to be dumped back at the forum list; you expect to remain within the forum. On the other hand, you do expect to find a link back to the forum list. This may seem trivial, but do try to actually use your forum and make sure navigation works well.

Further design comments: You may want to use coloring to separate the main part of a web page (a list of threads or messages) from the surrounding information, but if you do, this coloring should probably be subtle, such as using a light gray background instead of white. Borders may also be useful for this purpose, but if you use them, you should probably use subtle "flat" borders, not the default "three-dimensional" HTML borders.

These comments are not exhaustive. There's a lot more you need to think of when it comes to usability, but unfortunately it is impossible to list all potential mistakes explicitly. Please ask other groups to test your forum, and make sure that your lab assistant is involved now and then.

Internal Coding Requirements

We now continue with a number of requirements that are mainly invisible to the user but are important for the robustness and maintainability of your application.

Again, please read this section carefully.

Requirements: Using Packages

For this lab, all of your Java classes must be placed in packages. You should use the standard naming conventions for packages. For example, you might use a package named se.liu.ida.youremail.tddi48.forum. It will most likely also be a good idea to create subpackages under the forum packages. For example, you might want to have a separate subpackage for code related to user information and user databases, and one for code related to messages and message databases.

Of course, youremail should be replaced with your actual account name / email address, for example noone123.

Requirements: Documenting your code

We know that comments are the most boring thing there is, with the possible exception of bugs and exams. On the other hand, they are vital for anyone who has to read your code. Therefore all code you write in this project must be well commented and documented.

To be more exact, we will take the perspective of the poor guy who (one year after your project ended) has to try to understand your program in order to fix a couple of problems and add a few new features. From his point of view, you don't necessarily need any comments for trivial comments and fields, as long as they have well chosen descriptive names and do exactly what the names say. But he will need the following information, for example:

A common mistake is finishing your project and then starting to write comments. You can often save time by writing your comments and documentation before you write the code, since this means you really have to think about the way you design your program.

You can read more about javadoc on the javadoc home page.

For an example of good JavaDoc documentation, look at the API documentation for the Graphics2D class. For example, when you write a JavaDoc comment for a method, you should document what the method requires (requirements on parameters, etc), and what it promises (what effects it will have and what it will return — not how it does it). An outsider should be able to use the method by reading the comments, without having access to the code. Ideally, it should even be possible for someone else to implement the method given the JavaDoc information, because all the relevant information should be there.

Requirements: Documenting your JSP pages

Naturally, the JSP pages that you write should also be documented in some manner. You can use HTML-style comments, but they will also appear in the generated content and can therefore be seen by your users. Usually, JSP-style comments are a better choice.

Requirements: Coding Standards and Naming Standards

The code you write should not only work — it should also be well written and easy to read. This is of course a matter of judgement, but a minimum requirement is that you follow the Sun naming conventions for Java. This means following capitalization rules and other similar rules just like we do in the course slides.

You should also follow the most basic parts of the Sun coding conventions for Java. You can easily do this in IDEA by selecting Tools | Reformat Code to reformat your code to TDDI48/TDDB87 standards.

Requirements: Avoid unnecessary code duplication!

Code duplication should be avoided. Not at any cost, of course; sometimes a piece of duplicated code is not a major problem. On the other hand, we often see projects where the exact same 15 lines of code occur in two dozen JSP pages: "open database, check if we succeeded, if so retrieve the current user from the database, check if we succeeded, if not redirect to an error page", for example. This is a waste of space, a waste of memory, a waste of our time when we have to read the same code dozens of times, and perhaps most importantly, a major maintainability problem. If you have to change something in these 15 lines of code, you could easily miss one out of two dozen JSP pages – and if something is slightly different in these code segments in one or two pages, is that intentional or a bug?

As soon as you think "haven't I done something like this before?", you should also think "should this be extracted into a separate utility method or JSP include page?". Of course, sometimes the answer will be "no"...

Optional: Use a version control system!

IDEA provides excellent integration with version control systems such as CVS and Subversion. Teaching the basic use of version control is beyond the scope of this course, but if you are already familiar with version control systems and you have access to a repository where you can store your code, we strongly encourage you to do so.

Example: Once you have created a project in IDEA, you can set the version control system for your module using File / Settings / Version control. If you set the VCS to Subversion, you can then right-click the content root for your project and select Subversion / Share Directory. You will be asked for a Subversion repository and folder where your content root folder will be "uploaded". After doing this, you will also have to commit the current version of your project (Version Control / Commit changes). IDEA will automatically show you change bars indicating where changes have been made since the last commit, will allow you to browse changes or merge other project members' changes with your own, and so on. You will also be able to revert unsuccessful changes, annotate source files to see who last edited a certain line and when, and so on.

(Continued in part 1 of the project...)




Jonas Kvarnström


Valid HTML 4.01!   [Check links]