In this section the following is installed and configured, where necessary:

• MySQL: the database server
• Java SDK: this includes a JVM (Java Virtual Machine), and simple tools to compile/debug/run Java code.
• JBoss: the J2EE application server
• Eclipse: the Java IDE used to create and debug the J2EE application.

Each installation is covered briefly in the following sections.

MySQL is the relational database that is used. Only MySQL can be installed on a separate machine. All the other components (JBoss, JDK, Eclipse) should be installed on the same machine: it makes debugging and testing easier.

MySQL can be downloaded from www.mysql.com. There are different releases available for download. It is advisable to download the production release. Other releases are for people who are interested in the up and coming versions. The "Max" distribution is not used in this article.

For Windows, an exe can be downloaded and run. The documentation recommends downloading the "essentials" executable. The complete download contains a lot of utilities which are not used in most setups.

MySQL's web site also has tools to download. The MySQL Administrator and Query Browser are very useful. The Administrator provides a graphical front end to creating users, databases, tables and more. The Query Browser provides a graphical front end to view or update data in the databases, using sql queries.

On Linux, the preferred option is to download the server and the client rpm packages.

On the MySQL web site, there is a manual in PDF format. It's a good idea to download it. O'Reilly also publish an excellent book, called "MySQL Reference Manual", it's got everything the PDF file has, but it is easier to read.

Before running MySQL for the first time, it is important to read the documentation. There are certain post-installation steps which may need to be carried out. These may change as newer versions are released. Here are some of the post installation issues encountered:

Once installed, MySQL starts up and shuts down with Linux: the rpm packages install MySQL as a daemon. It is worth noting that if MySQL is installed as the Linux root user, it is likely that the database server will run as root. The manual explains how to change this. An alternative is to install MySQL as a less powerful user.

The "msi" installer is run. At the end of the installation, the configuration wizard should be run. If not, it can be launched from the start menu (programs->MySQL). The wizard can setup the root password, and allow connections to the database server from other computers. For this article TCP/IP connections to MySQL are enabled. This is because Java accesses the database using TCP/IP.

On Linux, the MySQL manual states that MySQL is not setup with a root password by default. Even on a development machine it is advisable to setup some database security (users, passwords).

Below is an example session using the command line MySQL tool. The anonymous user is removed, and a root password is setup:

The mysql command line tool is started as follows:

~> mysql -u root

The MySQL command line tool starts up with a welcome message. Below is the conversation carried out with MySQL to setup security on the database.

Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 4.0.18-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> use mysql;
     Database changed
mysql> show tables;
     +-----------------+
     | Tables_in_mysql |
     +-----------------+
     | columns_priv    |
     | db              |
     | func            |
     | host            |
     | tables_priv     |
     | user            |
     +-----------------+
     6 rows in set (0.03 sec)

mysql> delete from user where user = '';
     Query OK, 1 row affected (0.00 sec)

mysql> update user set password = password('password') where user = 'root';
mysql> flush privileges;
mysql> quit
     Bye
                        

>mysql -u root -p
     Enter password: ********
     Welcome to the MySQL monitor. Commands end with ; or \g.
     Your MySQL connection id is 9 to server version: 4.0.18-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> quit
     Bye

>

Note: it is possible to start the MySQL console with the username and password on the command line. However, when used across a network, the password is not encrypted. The recommended way to start MySQL from the command line is as shown above. When the password is entered, MySQL encrypts the password before sending it on to the MySQL server.

Security in MySQL can be quite involved. It is possible to restrict access based on the user, ip address or host. Different privileges can also be applied depending on whether the user is connecting from the local host or not. The MySQL reference manual explains this in a detailed manner.

That wraps it up for the installation of MySQL.

The Java SDK needs to be installed. This is because both the Eclipse IDE and the JBoss J2EE server require a JDK to be present.

The Java SDK can be downloaded from http://java.sun.com. The documentation is downloaded as a separate bundle. When downloading the JDK, it is important to make sure the correct download option is chosen. It is very easy to accidentally click the J2EE JDK download, the JDK SE is what should be downloaded and installed.

It is well worth downloading the JDK documentation. The documentation is a valuable reference for the various API's that are part of Java.

Linux Notes

The JDK can be downloaded as a self extracting binary or as an RPM.

The self extracting binary can be installed in any location on the system, it does not replace the version already installed as the system's Java.

The rpm download may or may not replace the version already installed as part of Linux. It all depends on the particular distribution and version of Linux being used.

In this article, the JDK used is the self extracting binary. It is the simplest to install and least likely to cause any system conflicts.

Java Documentation

The Java documentation is downloaded as a zip archive. The archive is extracted into the folder where the JDK was installed. In this way all the JDK related files are in one place (as shown below).

Setting the JAVA_HOME and PATH Environment Variables

The environment variable called JAVA_HOME is used by many Java applications, including JBoss. It is therefore necessary to make sure that this environment variable is setup correctly after Java has been installed.

On Windows Systems, in the control panel, the System icon is opened. The Advanced Tab is selected, and the "Environment Variables" button is pressed. A "New" user variable called JAVA_HOME is created, it's value is the root installation of the Java SDK.

On Linux, JAVA_HOME can be set in the .bashrc login script. In the following example, the PATH is updated to point to the latest JDK just installed, and JAVA_HOME is also setup.

export JAVA_HOME=/home/username/bin/jdk1.5.0_06
export PATH=/home/username/bin/jdk1.5.0_06/bin:$PATH

Installing JBoss

JBoss needs an environment variable called "JAVA_HOME" to be set to the root installation of the JDK. This must be set before JBoss is run. The previous section explains how this is achieved. The JBoss installation used in this article requires that the JDK be version 1.5 or greater. The JDK version currently on offer at Sun's site is always the latest one, and is greater than version 1.5.

JBoss is downloaded as a jar file from http://www.JBoss.org. The archive is an executable Java Archive, when run it launches the JBoss installer Java Application. Depending on how Java has been installed it is possible to launch the installer by double clicking the Jar file. Otherwise a command line window is opened in the directory where the JBoss jar file was downloaded, and Java is launched with the JBoss installer file as a parameter:

java -jar jboss-4.0.4RC11-installer.jar

The installation folder path of JBoss should not contain spaces. On Windows Systems, the path "C:\Program Files" is not advisable. Something like "C:\Programs\JBoss" is possible alternative:

For the purposes of this article, it is important to have EJB 3.0 support installed. At the time of writing EJB 3.0 is still very new, and so must be selected instead of the "all" EJB server option.

In subsequent dialogs, the JBoss default installation folder is checked. If the installation path has spaces in it, an alternative path is selected. In subsequent dialogs, the defaults are left alone. In most situations it may be necessary to change the admin password from its default ("admin").

Running JBoss For The First Time

JBoss should be started, just to make sure the JDK and JBoss are installed correctly, and to allow JBoss to make any final installation steps it requires. This is done by entering "run.bat" (Windows) or "./run.sh" (Linux) at the command prompt, in the JBoss bin folder.

A lot of text is output by JBoss, then it finally displays the line shown below (JBoss version numbers may vary):

If the console window displayed some Java Exception stack trace(s), they need to be resolved. With JBoss version 4.0.4RC1, no problems have been found.

To test that the server started correctly, a web browser is opened, and the following URL entered: http://localhost:8080/jmx-console/index.jsp, where localhost can be the name of the server on which JBoss was installed. A successful installation displays the "JMX Agent View" page.

To stop the server, either control C is pressed in the command prompt used to launch JBoss, or, a new command prompt is opened, and "./shutdown.sh -S" (Linux) or "shutdown.bat -S" (Windows) is typed. In the JBoss command window, the output shows that JBoss has shut down:

Most business applications need a database. To isolate the code from the database server used, JEE app servers use Datasources. JBoss allows different datasources to be setup. JBoss ships with a Hypersonic database. This database is used by JBoss in its day to day running, JBoss has a default datasource called DefaultDS which points to the Hypersonic database. It is possible to replace it with another database (MySQL, Ms SQL Server, Oracle 9i....). In this article, the Hypersonic database is left alone. It is possible to use an additional datasource (and DBMS) to store the application data for the applications we develop, this is what is done in this article.

A datasource is created so that a MySQL database called shoestring can be used along with this article.

The steps involve the following:

• copy the MySQL JDBC driver jar file to the JBoss server configuration
• create and deploy a datasource in JBoss

Connector/J is the official JDBC driver for MySQL, Connector/J can be downloaded from MySQL's web site: http://www.mysql.com. The JDBC driver download is available as a zip or tar.gz. This archive contains documentation, sources, a debug version of the driver and a production version of the driver. The production version of the driver is the one to extract and use.

Once downloaded, the archive is extracted into a temporary folder. The root folder of the extracted contents contains the file mysql-connector-java-3.1.12-bin.jar, this is the production version JDBC driver jar that needs to be copied to JBoss. The archive downloaded from MySQL contains documentation which explains which jar file is the production version of the JDBC driver.

This article uses the default JBoss configuration. The jdbc driver jar file is copied to the JBoss configuration called "default", in its lib folder (JBossRootInstallationFolder/server/default/lib).

A new file is created, this file describes the MySQL datasource, so that JBoss can use it. The new file is saved as shoestring-ds.xml in the deploy folder of the default JBoss server (JBossRootInstallationFolder/server/default/deploy). Below are the contents of the datasource file:

<datasources> 
   <local-tx-datasource> 
      <jndi-name>ShoestringDS</jndi-name> 
      <connection-url>jdbc:mysql://hostname:3306/shoestring</connection-url> 
      <driver-class>com.mysql.jdbc.Driver</driver-class> 
      <user-name>user</user-name> 
      <password>password</password> 
   </local-tx-datasource>
</datasources>
            

The hostname should be changed to localhost, if MySQL and JBoss are run on the same machine. Otherwise, hostname should be the name, or IP address, of the machine on which the database server runs. It is worth noting that the datasource name is ShoestringDS.

Installing Eclipse

Eclipse, the Java programmer's IDE used in this article, can be downloaded from http://www.eclipse.org. The download page is quite straightforward. The latest release is downloaded. It is possible to download other, less stable development (also called Milestone) releases. As a rule, if there is no known reason not to download the release version, it is safer to go for the release version.

The IDE is installed on the development machine by extracting the contents of the downloaded archive. The Java SDK should already be installed and ready to run.

After downloading and installing Eclipse, it needs to be run once. This allows Eclipse to complete its installation. In the root folder of the Eclipse installation the Eclipse executable (Eclipse.exe on Windows, eclipse on Linux) is launched by clicking on the icon.

Note:

Eclipse has a default location for all the projects. When running Eclipse for the first time it asks for the root folder where all projects are held. The default can be changed later on by starting eclipse with a parameter. For example:

C:\Programs\eclipse\eclipse.exe -data C:\Data\code2\Shoestring

The above launches Eclipse. Any new project is given a default location of C:\Data\code2\Shoestring.

It is advisable to settle for a location now : changing the default location later on can discard some plug in configurations.

With Eclipse running, it is worth making sure that Eclipse is configured to use the correct JRE. The Window->Preferences menu item opens a dialog to configure Eclipse.

Additional Java Runtime Environments can be added and selected.

Once the JRE is checked, the settings are saved by pressing OK, then the Eclipse program is closed. This is because in the next section, a plugin is added to Eclipse.

JBoss Eclipse IDE Plug-In

Eclipse is written to allow third parties to write a "plug-in". A plug-in can be installed to add functionality to Eclipse. Some plug-in's are available from the Eclipse site (http://www.eclipse.org), another good source is http://www.eclipseplugincentral.com, this last site lists many plug-in's for Eclipse. Some are commercial, some are free.

Plug-ins are extremely popular, it is well worth spending some time to get acquainted with what is on offer. Plug-in's are essentially third party "Wizards" that are used to simplify a particular programming or configuration task. They save time, and reduce the number of bugs in an application.

In this article JBoss is the J2EE server being used. The JBoss website lists a plug-in for Eclipse called Eclipse IDE. This plug-in facilitates the creation and debugging of Java applications which run inside JBoss. The plug-in is installed as follows:

With Eclipse running, the Help > Software Updates > Find and Install menu option is selected. The following dialog pops up, the second option is selected as shown below:

The next button is clicked, in the dialog shown below the "new remote site" button is clicked. The "JBoss IDE" name and URL ( http://download.jboss.org/jbosside/updates/stable ) are entered:

The OK button is pressed, and the "Finish" button is pressed on the Install dialog. Eclipse connects to the updates at JBoss, and lists the plug-in options found.

The JBossIDE1.5 entry is selected, and the "next" button is pressed. A license agreement is displayed. In order to carry on with the installation, the radio button labeled"I accept the terms in the license agreement" is selected, and the "next" button is pressed. A list of the features about to be installed is listed, the "finish" button is pressed to install all that has been selected so far.

The update manager fires up, downloads and installs all the features that have been selected.

After downloading all the components, a few alerts are thrown up, stating that some of the components are not signed, the option to install them is taken. Finally Eclipse asks to restart. This is done to ensure that the components are installed and registered with the Eclipse IDE.

Upon restarting Eclipse, the JBoss plug-in displays a dialog as shown below:

The next button is pressed, this allows JBoss to check for any old projects which may need updating. As this is a fresh installation, nothing needs to be updated.

That just about wraps up the installation for now. The next step is to write a few simple tests to ensure that everything is installed, configured and working together as expected.