Getting Started Guide

Programs should be written for people to read, and only incidentally for machines to execute.
- Abelson, Sussman
This guide gives you the basic information you need to install and run the example applications. This guide assumes you are using Tomcat 6+ as your web app container, and MySQL 5 as your database. You will need JDK 1.6 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's 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 below, 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 example applications aren't small. The tutorial is an alternative for those looking for a quicker introduction, and for those with less familiarity with Java web apps.

Table of Contents

Talking Computer Download
Populate The Database
Configure The Application: web.xml
Configure The Application: Captcha
Configure Tomcat: Jar Files
Configure Tomcat: Context File
First Launch
First Login
Main Links
Editing The Source
Adding New Users
Tomcat Manager
Disabling Login
Running Unit Tests

Download

The first step is to download the example app zip file (we recommend the Predictions app since it's simpler). Unzip your chosen zip file to a convenient location. That location is referred as APP_HOME below. Just to be clear, here are two example listings of the contents of APP_HOME, one for each example app: 
For APP_HOME = 'C:\TEMP2\predictions'
C:\TEMP2\predictions> dir /b
  css\
  images\
  main\
  pub\
  WEB-INF\
  build.xml
  Error.html
  ...

For APP_HOME = 'C:\myname\myprojects\fish\'
C:\myname\myprojects\fish\> dir /b
  access\
  all\
  exercise\
  images\
  main\ 
  translate\
  WEB-INF\
  webmaster\
  build.xml
  Error.html
  ...

Populate The Database

There is a single script for creating and populating the MySQL database. It's located in: 
[APP_HOME]\WEB-INF\datastore\mysql\CreateALL.SQL
The script has been validated against MySQL version 5.5.8. 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.

In the CreateALL.SQL script, you may have to replace 

DROP DATABASE/CREATE DATABASE
with 
DROP SCHEMA/CREATE SCHEMA

The script is run using the mysql client: 

[APP_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's 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).

This script sets the default encoding for all tables to UTF-8.

Configure 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's located in 
[APP_HOME]\WEB-INF\web.xml

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

It's 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.

Configure The Application: Captcha

This section applies to the Predictions application only. It doesn't apply to the Fish and Chips Club, which doesn't use a captcha.

A captcha is often used on the public web. They're used to prevent bots from creating accounts and putting spam into databases. The Predictions application implements a captcha using:

To use Predictions, you will need to create a recaptcha account. (Don't worry, it only takes a minute.) When you create an account, you will receive two items: a public key and a private key. These keys identify which app is calling the recaptcha server. Inside the Predictions app, you need to do two things with these keys:

Configure Tomcat: Jar Files

Two jar files must be made visible to Tomcat, and your application: To make them visible to your app, place them in:

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 at all.

Configure Tomcat: Context File

The example application needs to have its context file configured, and then copied into Tomcat.

Predictions context file: [APP_HOME]\WEB-INF\tomcat\predict.xml
Fish and Chips Club context file: [APP_HOME]\WEB-INF\tomcat\fish.xml

You must then edit the context file to match your environment. Remember to:

Please edit the context file 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 context file.

The context file specifies:

Here are two examples of a customised version of the context file. Compare them with your version, to see where you need to make changes specific to your own environment.

Important: the docBase attribute of the <Context> tag must point to your APP_HOME.

For predict.xml: 

<Context docBase="C:\TEMP2\predictions" reloadable="true">
 <Resource 
   name="jdbc/predict" 
   auth="Container" 
   type="javax.sql.DataSource" 
   username="fred"
   password="****"
   driverClassName="com.mysql.jdbc.Driver"
   url="jdbc:mysql://localhost:3306/predict?useServerPrepStmts=false"
   maxActive="10"
   maxIdle="5"
 />
 <Realm 
  className="org.apache.catalina.realm.JDBCRealm" 
  connectionURL="jdbc:mysql://localhost:3306/predict"
  digest="SHA-1"
  driverName="com.mysql.jdbc.Driver"
  roleNameCol="Role"
  userCredCol="Password" 
  userNameCol="LoginName" 
  userRoleTable="userrole" 
  userTable="users" 
  connectionName="fred"
  connectionPassword="****"
  debug="99"
 />
</Context>

For fish.xml:

<Context docBase="C:\bob\projects\fish" reloadable="true">
 <Resource 
   name="jdbc/fish" 
   auth="Container" 
   type="javax.sql.DataSource" 
   username="bob"
   password="****"
   driverClassName="com.mysql.jdbc.Driver"
   url="jdbc:mysql://localhost:3306/fish?useServerPrepStmts=false"
   maxActive="10"
   maxIdle="5"
 />
 <Resource 
   name="jdbc/fish_translation" 
   auth="Container" 
   type="javax.sql.DataSource" 
   username="bob"
   password="****"
   driverClassName="com.mysql.jdbc.Driver"
   url="jdbc:mysql://localhost:3306/fish_translation"
   maxActive="10"
   maxIdle="5"
 />
 <Resource 
   name="jdbc/fish_access" 
   auth="Container" 
   type="javax.sql.DataSource" 
   username="bob"
   password="****"
   driverClassName="com.mysql.jdbc.Driver"
   url="jdbc:mysql://localhost:3306/fish_access"
   maxActive="10"
   maxIdle="5"
 />
 <Realm 
  className="org.apache.catalina.realm.JDBCRealm" 
  connectionURL="jdbc:mysql://localhost:3306/fish_access"
  digest="SHA-1"
  driverName="com.mysql.jdbc.Driver"
  roleNameCol="Role"
  userCredCol="Password" 
  userNameCol="Name" 
  userRoleTable="UserRole" 
  userTable="Users" 
  connectionName="bob"
  connectionPassword="****"
  debug="99"
 />
</Context>

After the above edits are saved, simply copy the context file into the directory named 

[TOMCAT_HOME]\conf\Catalina\localhost\

If the above directory doesn't exist, then just create it. If Tomcat is running, then it will deploy the application.

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:

For purposes of comparison, example log files are included, under [APP_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 example application successfully. Hallelujah!

To test the JSP taglib configuration, a simple test page has been provided, called TestTags.jsp. It's located in the root of the web app. Example URLs: 

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

First Login

Navigate to the context path you defined in the context file (predict.xml, fish.xml) : 
http://localhost:8080/predict/
http://localhost:8080/fish/

Predictions will let you view some pages, without needing to login in immediately (in the style of most public web apps). Fish and Chips Club, on the other hand, forces you to login in immediately (in the style of most intranet apps).

Either way, you can log in with user name 'testeD', and password 'testtest'.

It's important that you understand the mechanics of the login mechanism, so that you don't bookmark the wrong item. That is, you're not supposed to bookmark the login page itself. It's natural to find this confusing. Rather, you're supposed to bookmark the home page (or some other page you are interested in). Then, when you navigate to that bookmark, and you're already logged in, then you won't be bothered with a second, unnecessary login. But, if you are not logged in, then a security-constraint defined in web.xml which protects that URL will be activated, and you will be asked to provide a 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 Predictions example app is pretty simple.

The Fish and Chips 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.

Editing The Source

You may of course edit the source. It's 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, but the other tools are nothing to get excited about.)

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's 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.

Predictions

The Predictions app follows the style of most public web apps. Creation of user accounts is handled by the end user. The steps are:

Fish and Chips Club

Th Fish and Chips Club mimics the style of most intranet applications. Creation of accounts is controlled not by the user, but by some other party within the organization. For intranet apps, it's a common requirement to:

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's convenient to disable login during development. To disable login, edit [APP_HOME]\WEB-INF\web.xml, and comment out these items :

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.