WEB4J. Because simple is beautiful.

Fish & Chips Club Getting Started Guide

This guide gives you the basic information you need to install and run the Fish & Chips Club example application. (The same general steps are used to install and run the Predictions example application as well.) This guide assumes you are using Tomcat 5 as your web app container, and MySQL as your database. You will need JDK 1.5 or better.

The most effective way to learn a framework is by examining and understanding a non-trivial application that uses it. Learning by just reading API documentation is often slower, since it is harder to see how your applications will work in practice. Any framework that doesn't give you such an example application isn't doing you any favors.

Since .class files are included in the download, there is no initial need to perform a compile before running the application. Once you modify the source, then a compile will be needed in order to see your changes.

(If you have followed these steps but still cannot launch the app successfully, just ask for email support. Please include log files, if any, and a description of the problem.)

The Fish & Chips Club is not a small application. It's meant as a kind of informal "reference implementation", and it exercises almost all of web4j's features. The tutorial is an alternative for those looking for a quicker introduction, and for those with less familiarity with Java web apps. As well, the Predictions example application, significantly smaller than the Fish & Chips Club, is also suitable as a learning tool.

Table of Contents

Download
Configuring The Application : web.xml
Populating The Database
Configuring Tomcat : <Context>
Configuring Tomcat : Jar Files
First Launch
First Login
Main Links
Editing The Source
Adding New Users
Tomcat Manager
Disabling Login
Running Unit Tests
Using a .war File

Download

The first step is to download the fish.zip file, and unzip it to a convenient location. That location is referred as FISH_HOME below. Taking FISH_HOME as 'C:\myname\myprojects\fish\', for example, the result of unzipping will look like this:

C:\myname\myprojects\fish\
  access\
  all\
  exercise\
  images\
  main\ 
  translate\
  WEB-INF\
  webmaster\
  build.xml
  Error.html
  ...

Configuring The Application : web.xml

Every web application based on servlets uses a web.xml file for configuration. Its official name is the deployment descriptor. It is located in

[FISH_HOME]\WEB-INF\web.xml

There are a number of settings in the Fish & Chips Club deployment descriptor. When getting started, the only ones you should likely set are:

• MailServer - mail server used to send TroubleTicket emails. This setting must be the server which is 'native' to your network. If you receive a "Relaying Denied" error, change this setting. Use 'NONE' to suppress emails entirely.
• Webmaster - the 'from' address on emails sent by the application. Must be on the same network as used by the MailServer setting. For example, if you are on blah.com, then the Webmaster might be support@blah.com, while the MailServer might be smtp.blah.com.
• LoggingDirectory - location for application log files. Must end with a separator, as in 'C:\log\fish\'.
• TroubleTicketMailingList - who to inform in case of trouble.
• DefaultUserTimeZone - default time zone for the application, in the format used by TimeZone. Example values : UTC, America/New_York.
• RedirectWelcomeFile - Redirects directory requests to the home page Action. Depends on context and port.

It is important that you edit these items before attempting to launch the application. The logging directory is particularly important, since upon startup the first action is to emit simple logging statements to confirm that logging is working as expected.

Populating The Database

There is a single script for creating and populating the MySQL database. It is located in :

[FISH_HOME]\WEB-INF\datastore\mysql\CreateALL.SQL

The script has been validated against MySQL versions 3.23 and 5.0. If you want to use a different database other than MySQL, then the script will need to be ported to the new target database. However, you need to be aware that there a number of settings in web.xml that are also sensitive to the database. To avoid problems with those relatively minor settings, you are strongly encouraged to use MySQL during this introduction to WEB4J.

The script has 3 sections, corresponding to the 3 databases it creates:

Database Name	Description
fish	Main problem domain
fish_access	Users and roles
fish_translation	Translation of user interface text

The script is run using the mysql client :

[FISH_HOME]\WEB-INF\datastore\mysql>C:\mysql\bin\mysql --local-infile=1 -u myname -pmypass < CreateALL.SQL

The above example runs the .SQL script directly from the directory where it resides. You will need wide permissions in order to run the script.

It is important to note that the user and role tables contain entries suitable only for testing. If you build a 'real' application from this example application, you will need to remove such entries. Note as well that user passwords are protected by being stored in a hashed form. You can enter new user names and passwords only through the application, not by direct manipulation of the tables (see below).

The UTF-8 encoding is highly recommended for your database.

Configuring Tomcat : <Context>

The example application needs to have its "<Context>" configured in Tomcat. You simply copy the file named

[FISH_HOME]\WEB-INF\tomcat\fish.xml

into the directory named

[TOMCAT_HOME]\conf\Catalina\localhost\

If the above directory doesn't exist, then just create it.

You must then edit fish.xml to match your environment. Remember to :

• change user names
• change passwords
• change the docBase attribute to match your [FISH_HOME] directory

Please edit fish.xml with care. Any mistake will cause the launch of the app to fail. If you have a problem launching, the cause is almost always with the fish.xml file.

The fish.xml context specifies :

• database connections
• a 'security realm', needed for log in operations handled by Tomcat
• mapping your FISH_HOME directory to a URL path or 'context'. This mapping is a way of deploying an application directly, without needing to create a .war file. Instead of a giving Tomcat a .war file, it's simply instructed on where to find the web app implementation on the local file system. This is the preferred style when developing, since there is no need to go through a build-and-deploy cycle in order to see updates.

Configuring Tomcat : Jar Files

Two jar files must be made visible to your application :

• the database driver
• junit.jar

To make them visible to your app, place them in

• Tomcat 6: [TOMCAT_HOME]\lib\
• Tomcat 5: [TOMCAT_HOME]\common\lib\

It's a bit silly to require junit.jar for a deployment. The reason it's required is because WEB4J loads all classes in your app upon startup, and examines them using reflection. In a production deployment, you would likely remove all JUnit test classes, and there would be no need for junit.jar.

First Launch

To launch the application, start Tomcat. Check the log file, located in the LoggingDirectory you configured in web.xml. There should be a new time-stamped log file in that directory. If there is no log file, then a problem has occured. If so, check the Tomcat logs located in [TOMCAT_HOME]\logs. Tomcat uses several log files, so look around the various files. Look for stack traces, and anything logged at SEVERE level. Possible causes of error:

• typo while editing web.xml or fish.xml has rendered the file syntactically invalid.
• missing .jar files
• problem with JSP tag libraries
• your environment doesn't meet the requirements somehow

For purposes of comparison, example log files are included, under [FISH_HOME]. A successful launch will end with the time it has taken to initialize the app (usually about a second). If you see such a message, then congratulations, you have launched the Fish & Chips Club successfully.

For testing JSP taglib configuration, a simple test page has been provided, called TestTags.jsp. It's located in the root of the web app. An example URL:

http://localhost:8080/fish/TestTags.jsp

First Login

Navigate to the context path you defined in fish.xml :

http://localhost:8080/fish/

(This is valid if Tomcat is running on its default port 8080.)

Login with user name 'testeD', and password 'testtest'. (Here are screenshots of the login page, and the home page, for reference.)

It is important that you understand the mechanics of the login mechanism, so that you don't bookmark the wrong item. That is, you are not supposed to bookmark the login page. It's natural to find this confusing. Rather, you are supposed to bookmark the home page (or any other page you are interested in). Then, if you are already logged in, you will not be bothered with a second, unnecessary login. But if you are not logged in, then the security-constraint defined in web.xml which protects that URL will be activated, and you will be asked for user name and password in the usual way.

This kind of behavior is defined by the servlet specification's form-based login mechanism. Once you understand this mechanism, you can see that attempting to bookmark the Login.jsp page itself does not make sense: after successful login, Tomcat would not know where you 'really' wanted to go.

Main Links

The example app has distinct modules. Users can access the various modules only if they have been assigned the proper role. (The user name mentioned in the previous section has wide open permissions.) Here are the links to the main page in each module. These links are valid for the default Tomcat port 8080, and with 'fish' as the context path. Please amend as needed.

• Main home page - link
• Webmaster module - link
• Access Control module - link
• Preferences module - link
• Translation module - link
• Exercise module - link

Editing The Source

You may of course edit the source. It is likely best to use a modern IDE, such as IntelliJ Idea, NetBeans, or Eclipse. Many IDEs can automatically compile as you edit. In addition, Tomcat will automatically refresh the app when it detects changes.

The startup time is short - usually under a second. When you have configured Tomcat's <Context> as described above, where the context is mapped directly to the source code root directory, then you can see your changes reflected quickly, without an extended waiting period.

You can also use the WEB4J Developer Tools to speed up your development. (The Log Viewer is particularly useful.)

Adding New Users

Usually, you will want to create a more convenient user name and password. This must be done through the screens provided by the application itself, and not by editing the access control database tables directly. The password is stored in a hashed form, in order to keep it secret. The hash function is defined in Java, not in MySQL. So, it is not possible to add a new user correctly by using only MySQL tools.

In the beginning, adding a new user will seem unnecessarily painful. There is some inconvenience, but there's a reason for the inconvenience. The whole idea of an example application is to mimic what a 'real' application might do. In the case of security, it is a common requirement to

• separate out the user maintenance role to people who are explicitly assigned that single role
• assign one or more roles to each user

To add a new user, navigate to the Access Control module:

http://localhost:8080/fish/access/user/UserAction.list

Login as 'testeD', as described above. (This user has wide privileges.)

You add a new user in two steps :

1. add a user name (Users screen).
2. assign one or more roles to the new user name (Roles screen). If you are adding a new user name for yourself, you usually want to assign every role to yourself. Otherwise, you will not have access to all features.

When a new user is added, they always receive the default password

'changemetosomethingalotmoreconvenienttotype'

This password is intentionally inconvenient, so that the user will be motivated to change it. After login, any user can change their password at any time by navigating to the Preferences screen. (This is simply an example of a particular password policy. Many others are possible.)

Tomcat Manager

Tomcat comes with a simple tool for managing your deployed web applications, called Tomcat Manager. It has a nice reload mechanism, whereby you may reload your app, when needed, simply through a browser refresh. It's always best to reload an application instead of the server, since a server restart takes longer.

Tomcat Manager requires login. You need to add an entry to [TOMCAT_HOME]\conf\tomcat-users.xml, such that a user has the role of 'manager'. Here is an example entry:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <user username="blah" password="blah" roles="manager"/>
</tomcat-users>

The tool is accessed using :

http://localhost:8080/manager/html/list

Disabling Login

Sometimes it is convenient to disable login during development. To disable login, edit [FISH_HOME]\WEB-INF\web.xml, and comment out these items :

• all <security-constraint> tags
• in older versions of web4j (previous to version 4.3.0 of September 2009), you also need to comment out the <filter-mapping> tag which enables the CsrfFilter

Running Unit Tests

Please see the User Guide for instructions on running the unit tests provided with the example application. The unit tests are implemented using various test doubles, whose source code is provided in the example application.

Using a .war File

The above style of pointing directly to the development directory is highly recommended. If you need to use a .war file, then :

• change the file extension of fish.zip to fish.war
• place fish.war in [TOMCAT_HOME]\webapps\
• follow the above instructions regarding fish.xml, and remove the docBase attribute
• start Tomcat

Tomcat will unzip fish.war when it launches the application. In this style, the initial 'unzip' of fish.zip into an arbitrary development directory (performed above in the first step) is not used by Tomcat.