Building the Source Code

We use Ant to build the source code. The file build.xml contains the definitions of all the Ant targets. Open this file now and take a look at it. It's a reasonably standard kind of Ant build file. The targets are:

• clean. This target deletes the bin directory, which is used to hold all of the compiled Java class files and various other resource and data files. It also deletes the javadoc directory, which is used to hold the generated javadoc.
• init. This target creates new empty bin and javadoc directories if they don't already exist, then copies a large number of resources and other files from the properties and src directories into the bin directory, if they haven't already been copied or there are newer versions in the source directories.
• compile (depends on init). This target compiles all of the new or changed Java source code files in the src directory and places the compiled class files in the bin directory.
• hibernate (depends on compile). This target runs the Hibernate XDoclet to extract Hibernate declarations from the persistent object model Java source code files. The declarations are used to create *.hbm.xml files in the bin directory. Hibernate uses these XML files at run-time to define the mapping from our object model to the MySQL database.
• rmic (depends on compile). This target runs the Java rmic compiler to generate stubs for the remote classes in the server.
• bin (depends on hibernate and rmic). This is the default target. It copies new or changed resource and data files, compiles new or changed source code files, and runs the hibernate and rmic targets.
• full (depends on clean and bin). The full build target. It runs the clean target first, then recopies and recompiles everything and runs the hibernate and rmic targets.
• doc (depends on init). Builds the javadoc. In the WordHoard development team at Northwestern, we have a policy that all classes and methods must have complete and error-free javadoc.

At this point you want to do a full build. We use our alias b to run Ant:

% b full

You should now have a fully compiled copy of WordHoard in your bin directory, which is in your classpath.

The next step is to create the server database wordhoardserver. Use the create-server-database script to do this:

% scripts/create-server-database.csh

Use the MySQL command line client to make sure the database was created correctly:

% mysql
mysql> use wordhoardserver;
mysql> show tables;
+---------------------------+
| Tables_in_wordhoardserver |
+---------------------------+
| account                   |
| userannotation            |
+---------------------------+
2 rows in set (0.00 sec)

mysql> quit

Run the mysql-server-grants script:

% scripts/mysql-server-grants.csh

This script grants all privileges on the wordhoardserver database to the account with username wordhoardserver and password wordhoardserver, but restricts access to localhost. This makes the wordhoardserver database private, readable and writable only by programs running on the same host (e.g., the WordHoard server program).

Use the start alias to start the WordHoard server in the background. Wait for the "WordHoard server started." message to appear:

% start
[1] 14366
WordHoard server started.

Use the r alias to run the WordHoard client:

% r

Try playing around with the program to make sure it works. Read some text. Get info on a word. Do a search.

Login using the username "admin" and password "admin". Open the "Manage Accounts" window. You will see that there is a single account defined, "admin", with account management privileges. Try creating another account with username "fred", name "Fred Flintsone", and password "mary", to make certain the server works.

Quit WordHoard.

Try making a trivial change to the WordHoard source. Open the following resource file:

src/edu/northwestern/at/wordhoard/resources/wh.properties

Change the version number of the program near the top of the file (in two places) and save the modified file.

Test your change by running Ant to build the default bin target:

% b
% r

Open WordHoard's about box. You should see your new version number.

Check the server log file. You should see several log entries for server startup, the two times you ran the client, and a message when you logged in as "admin":

% more server/data/log
2005-12-15 14:46:05,312 INFO  - Server started, version 1.0fc5
2005-12-15 14:48:28,671 INFO  - Session=0: <null>, Session begin: 129.105.110.29
2005-12-15 14:48:39,851 INFO  - Session=0: admin, Login
2005-12-15 14:48:52,540 INFO  - Session=0: admin, Session end: 129.105.110.29
2005-12-15 15:31:49,742 INFO  - Session=1: <null>, Session begin: 129.105.110.29
2005-12-15 15:41:28,055 INFO  - Session=1: <null>, Session end: 129.105.110.29

Check the server database account table to make sure your "fred" account was created correctly, and the password "mary" was properly encrypted before being stored on the database:

% mysql
mysql> use wordhoardserver;
mysql> select * from account;
+----+----------+---------------+-----------------+-----------+-------------------+
| id | username | password      | name            | nuAccount | canManageAccounts |
+----+----------+---------------+-----------------+-----------+-------------------+
|  1 | admin    | adpexzg3FUZAk | Administrator   |           |                  |
|  2 | fred     | maO6ZbdtofDIg | Fred Flintstone |           |                   |
+----+----------+---------------+-----------------+-----------+-------------------+
2 rows in set (0.00 sec)

mysql> quit

Stop the server:

% stop
WordHoard server stopped

If all these tests worked, you are ready to start writing and testing your own WordHoard code.

At some point (maybe now would be a good time), you will want to change the password on the "admin" account, and perhaps delete the "fred" account you used for testing, and probably change the version number back to what it was before you changed it to do your test.

Note that if you are not working on server code or on parts of the client that require logging in, you do not need to run the server when you are developing and testing your code.