TDDI48 Project Part 1: Setup

Written by Jonas Kvarnström with modifications for 2006–2007 by Martin Magnusson. Please report any bugs, inconsistencies or vague requirements as soon as possible.

As the first part of the project you will set up the development environment that will be used throughout the project. The steps for this part are listed below.

  1. Setting up a web server.
  2. Setting up a database.
  3. Setting up an IDEA project.

Step 1: Setting up a web server

The message forum will contain a number of servlets and/or JSP pages that must be executed in a web server. In order to create a realistic environment (and to avoid clashes between different lab groups), each lab group will be running its own instance of the Caucho Resin web server.

1.1: Installing Resin

Start by installing the Resin configuration files in your home directory. This is done only once! 

  ~TDDI48/bin/install-resin.sh

This creates a directory called resin in your home directory. You must also add the resin module: 

  module add /home/TDDI48/modules/resin/3.0.17
  module initadd /home/TDDI48/modules/resin/3.0.17

Configuring the Resin port number

Before you actually start using Resin, you must configure it to use a unique port number that will not clash with the port numbers used by other people that may running servers on the same computer that you use (remember that the SunRay computers are thin clients, "terminals" connected to central servers). Change ~/resin/conf/resin.conf as follows. First, locate the line saying <http server-id="" host="*" port="8088"/> and change the port number from 8088 to another random number . Second, completely delete the following lines from the configuration file: 

  <cluster>
    <srun server-id="" host="127.0.0.1" port="6802" index="1"/>
  </cluster>

Running Resin

To start, stop, and restart Resin, use the following commands: 

  ~TDDI48/bin/resin.sh start
  ~TDDI48/bin/resin.sh stop
  ~TDDI48/bin/resin.sh restart

After installing Resin, make sure that it works correctly by pointing your browser to http://localhost:yourChosenPortNumber. The web page you see is taken from the webserver root resin/doc that contains an example index.html file.

Configuring Resin

The main configuration file is in resin/conf/resin.conf. Here you can set things like the http port, or configure locations of log files.

TOOLS: Note that you should be using Mozilla or Firefox as a web browser. These are currently the most standards-compliant browsers available on the Sun machines. Opera might also be a good choice if it is available on your machine. Internet Explorer is not recommended, due to its poor support for CSS and other standards.

1.2: Set up a web application in Resin

The message forum will be written as a single Java/JSP web application. There is already one web application configured in Resin, the default web application, which serves files from the ~/resin/doc directory. This web application was configured in ~/resin/conf/resin.conf as follows: 

  <document-directory>doc</document-directory>

  <!-- configures the root web-app -->
  <web-app id='/'>
    <!-- adds xsl to the search path -->
    <class-loader>
      <simple-loader path="$server-root/xsl"/>
    </class-loader>

    <welcome-file-list>
      <welcome-file>index.xtp</welcome-file>
      <welcome-file>index.jsp</welcome-file>
      <welcome-file>index.html</welcome-file>
    </welcome-file-list>

  </web-app>

Your message forum web application should of course be a separate web application, not mixed up with the default application. Though you won't be writing any servlets or JSP documents just yet, you will soon begin writing some HTML web pages and forms, so we'll have to start configuring the web application right now.

As a first step, create a directory for the web application: ~/resin/doc/tddi48.

Right now the server only considers this to be an ordinary directory within the default webapp. To make it a separate webapp, add the following to ~/resin/conf/resin.conf, after the default webapp configuration (right before </host>): 

  <web-app id="forum" document-directory="tddi48"/>

Create a very simple "hello world" web page at ~/resin/doc/tddi48/index.html. You will write a better page later, so don't spend much time on it.

If you wait a minute, Resin should discover that you changed its configuration file. Resin should automatically restart. Some versions of Resin also indicate this by printing "Resin httpd restart at..." to the window from which you started it.

If you don't want to wait a minute, run ~TDDI48/bin/resin.sh restart to restart the server manually. (If you keep getting "Resin httpd restart at..." messages, you made a mistake in the configuration file; check the logs in ~/resin/logs and try to find out where the error is.)

When Resin has finished restarting (which might take 10 seconds after the message is printed), try taking a look at http://localhost:yourChosenPortNumber/forum/. The context path /forum should now be mapped to the tddi48 directory, and you will see your new index.html document.

(Why does the server send index.html when you asked for the forum/ directory? Because resin.conf has a reference to app-default.xml, and app-default.xml specifies a <welcome-file-list> that includes index.xtp, index.jsp, and index.html. You can change this in your own webapp if you want the default "welcome page" to be called something else.)

If Resin has not already done this for you, you should also create a directory called ~/resin/doc/tddi48/WEB-INF. This directory will be used when you start doing more complex tasks with your web application. For example, servlet code and the web.xml deployment descriptor will go into this special directory. For now, you can leave the WEB-INF directory empty.

Step 2: Setting up an IDEA project

If you decide to use IDEA (which we strongly recommend), you will have to install the IDEA configuration files and set up a project.

2.1: Installing IDEA

Before you use IntelliJ IDEA you must install the IDEA configuration files in your home directory. This is done only once! 

  ~TDDI48/idea/ideaconfig6.sh

This creates a directory called .IntelliJIdea60 in your home directory and copies some configuration files to that directory.

You must also add the JDK 5.0 module: 

  module add prog/jdk/5.0
  module initadd prog/jdk/5.0

2.2: Starting IDEA

Several versions of IDEA have been installed in parallel. New updates will be installed as they are released and will be announced on the course home page.

At the time of writing, the most recent version is IDEA 6.0.4 build 6148. To start it, use the following command: 

    ~TDDI48/idea/idea-6148/bin/idea.sh

If new versions of IDEA are installed, you may have to change this command line to reflect the new version number.

2.3: Creating an IDEA project

You will have to provide quite a lot of information in order to configure IDEA for your project, but fortunately this only has to be done once. Please make sure that you follow these instructions carefully! Print them out, and mark everything you have done so you don't lose your place and miss a step. If anything is unclear, please ask us.

The New Project Dialog

The Settings Dialog

When you have finished the New Project wizard, there are a few more things to configure in the Paths dialog. Open this dialog by using File | Settings (Ctrl-Alt-S).

Click the Project Structure icon.

You can now press OK, close the settings window, and finally start working with your project.

The Project Pane / Project Tab

Take a look at the files available under the Project tab in the project pane (if it is not visible, select Window | Project: Alt-1 or click the "1: Project" tab on the left hand side of the screen).

You should see your src and resources directories there. The src directory is blue, to indicate that it can contain Java source code. You should also see a web.xml file, though it may not contain much yet.

The Project Pane / J2EE tab

Also take a look at what is available under the J2EE tab of the project pane. The J2EE tab permits you to access web-specific functionality.

As you can see, the src directory that you created previously is not shown here. This is a web application view, which shows servlet configuration items (once you have added them) but not general Java classes. On the other hand, the resources directory is shown, though it looks a bit different. It is blue, with a tiny yellow-and-blue globe, indicating that it is a web resource directory.

In the J2EE tab, double-click the ForumModule (a blue-and-yellow globe). The result will be a property page where you can configure servlets and a few other properties related to the web module.

Fill in a display name, such as "FooSoft Message Forum".

Fill in a description for your message forum web application.

You should not check "distributable". This is for web applications that can be distributed over multiple computers in a cluster.

Note that there is no "OK" or "cancel" button. The property page is saved along with other information when you "save all".

Double-click web.xml, and you will see some of the configuration properties that you specified previously. If you ctrl-click one of the tags (such as <description>) you can see its definition in the deployment descriptor DTD. There are also comments describing how each tag is used.

If web.xml is almost empty, IDEA may not yet have saved your display name and description to this file. Press Ctrl-S and see whether the file changes.

Step 3: Setting up a database

You should now start the database server and create a database together with a table in which user information should be stored.

3.1: Installing and running MySQL

In this lab, we will be using the MySQL database server. To use MySQL, you must add the module office/mysql/4.1.7. You may also want to initadd the module, so that it is always available when you log in: 

  module add office/mysql/4.1.7
  module initadd office/mysql/4.1.7

You might also have to run the built-in shell command rehash to make the shell update its internal caches (otherwise it might not find the mysql_install_db or temp_mysqld commands even though they really are in your path).

(MySQL 5.0.22 is also installed on the lab computers. You may use this version if you wish, but it has not been tested in the forum project and you are unlikely to need any of the new features available in MySQL 5.)

Creating a database

The first time you use the database server, you must create a configuration file where you define a port number to be used and a location for the mysql.sock special file. The reason why this must be done manually is that many of you may end up running on the same computer, and each of you must be running your database server on a unique port number.

To configure these settings without having to give additional arguments to mysql for every invocation, you should create a new file called ~/.my.cnf where you add the following items: 

  [client]
  port=47111  # choose a random number
  socket=/home/noone123/mysql.sock   # noone123 = your email
  [mysqld]
  port=47111  # same as above
  socket=/home/noone123/mysql.sock  # same as above

The port number that you chose at random will also have to be used in JDBC URL you use in your database classes. A JDBC URL for MySQL has the form jdbc:mysql://[hostname][:port]/[dbname], where the port number is the same one you specified in .my.cnf.

Once you have created the ~/.my.cnf file as described above, you also have to create a few system tables and create a new database. You can do this as follows:

Next time you want to use the database, you will only need to start temp_mysqld (still in the foreground; don't use &).

To learn more about using the command line program mysql and the MySQL database in general, you can read the documentation available at the MySQL web site. You can also read the following two brief tutorials (not written by the authors of MySQL): Beginning MySQL Tutorial and MySQL Basics. More articles on MySQL are available at DevShed.

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

[Check links]

Jonas Kvarnström