Revision History

Version 2.1 - 1/11/04

• Shifted hosting to my personal website.
• Added links to sql scripts and made minor changes to JPetStore - Database.

Version 2 - 12/30/03

• Changed tutorial to HTML format.
• Included Linux-Friendly MySQL scripts (thanks to Maria Tzvetanova).

Version 1 - 10/13/03

• Original Writing

Motivation

I made this walkthrough in the hopes of saving someone some time when installing Clinton Begin's excellent JPetStore application.

This guide will walk you through the steps involved in setting up a Windows system to run JPetstore. It does not assume any prior installation/configuration of dependent software.

Linux Note:

The steps in this walkthrough are generally the same for a Linux installation.

Maria Tzvetanova pointed out that the lowercase table names in the mysql setup scripts In Version 1 caused errors when used on Linux systems. This is because (unlike Windows) MySQL on Linux is case-sensitive. She has supplied updated mysql scripts with uppercase table names which are included in Version 2.

Special Note: Transactions

The MySQL scripts that come with this walkthrough set up tables of the default (ISAM) type. These tables do NOT support transactions but are very fast. The MySQL driver is smart enough to act as if transactions occur so that transaction-aware software (like JPetStore) will still run fine. But in reality, each SQL command is a seperate "transaction".

If you need transaction support, use the MySQL script that comes with the JPetStore distribution (in the ddl/mysql directory). That file uses INNODB tables which do support transactions.

You will still need to set up a user so you can still use the jpetstore-mysql-create-user.sql script.

Walkthrough

1. Java
1. Download Java SDK 1.4.2_01 (had trouble using the NetBeans bundle so I recommend using the regular SDK package).
2. Tomcat
1. Download and install the latest version of Tomcat from http://jakarta.apache.org/site/binindex.cgi.
   
   1. I install all my Apache apps to "c:\program files\apache" to keep it simple.
   2. Just keep all the other defaults the same, and input your preferred admin password when prompted.
2. Start Tomcat. You can use either the Windows Service or the Start Menu shortcut, "Start->Programs->Apache Tomcat 5.0->Start Tomcat".
3. Verify that Tomcat is working correctly.
4. Goto http://localhost:8080. If you see a Tomcat base page you're good.
5. Goto http://localhost:8080/jsp-examples and try out a couple of the examples to confirm that Tomcat is working properly.
   
   Note: I had trouble getting the example, http://localhost:8080/jsp-examples/jsp2/misc/config.jsp to work. To fix this exception I followed the on-screen instructions and copied "$JAVA_HOME/lib/tools.jar from the JDK to the common/lib directory of the Tomcat server, followed by a Tomcat restart." :)
3. JPetStore - Download
1. Download and unzip the latest version of JPetStore to a temp directory.
4. MySQL
1. Download MySQL 4.0.14b, unzip, and run Setup.
2. Goto your default MySQL directory (C:\mysql for me) and copy my-medium.cnf to my.cnf. Now move my.cnf to C:\.
3. Open a command prompt (Dos prompt). Now goto, "C:\mysql\bin" and run, "mysqld-nt -install". This will install the MySQL daemon (server) as a Windows Service that will start automatically when Windows starts. You can verify this by going to Start->Control Panel->Administrative Tools->Services under Win2000.
4. Start the MySQL Service.
   

   Win2000:

   Go to Start->Control Panel->Administrative Tools->Services.

   Double-click the MySQL service

   click the Start button.

5. Set Root MySQL password.     *** Very Important Step ***
   1. Goto "C:\mysql\bin".
   2. Run "mysqladmin -uroot password NEW-PASS" where NEW-PASS is your password of choice.
      
      Note:Don't type the quotes...
   
   
   
6. Verify MySQL is running correctly.
   1. Run "mysql -uroot -p". You will be prompted for a password. Just enter in whatever you typed for NEW-PASS.
   2. You should see a "mysql>" prompt. If not, check Google for whatever error code you received.
   3. Run "show databases;".
      
      Note: Don't forget the ';'. If you ever see a prompt with just a " ->" then you know you forgot the ';'.
   
   
   
   4. If you don't see,

      +----------+
      | Database |
      +----------+
      | mysql    |
      | test     |
      +----------+
      2 rows in set (0.02 sec)
      	

      then you know something is wrong...try Google.
5. MySQL JDBC Driver
1. Download the MySQL JDBC Driver, mysql-connector-java-3.0.9-stable.
2. Unzip the driver. Copy the file, "mysql-connector-java-3.0.9-stable-bin.jar" to Tomcat's common/lib directory.
6. JPetStore - Database
1. Now download these files to your computer:
   jpetstore-mysql-schema.sql
   jpetstore-mysql-dataload.sql
   jpetstore-mysql-create-user.sql
   
2. Jump back to your shell prompt and execute the following commands.
   Note: Make sure you logged out of mysql.
   
   1. "mysql -uroot -p < jpetstore-mysql-schema.sql"
   2. "mysql -uroot -p < jpetstore-mysql-dataload.sql"
   3. "mysql -uroot -p < jpetstore-mysql-create-user.sql"
   Note: If you get an error like this: "mysql: command not found" that means you don't have the mysql program in your path. Just copy the '*.sql' files to your mysql/bin folder and run the commands from there.
3. If you don't see any errors, it worked correctly.
7. JPetStore - Deploy
1. Find jpetstore.war in the build/wars folder of wherever you unzipped the JPetStore download to.
2. Copy jpetstore.war to your Tomcat/webapps folder. For me this was at "C:\Program Files\Apache\Tomcat 5.0\webapps". Tomcat will automatically deploy your app if you have it started. If it's not started just follow the instructions in step 2.
3. Don't try to access (run) the app yet.
8. JPetStore - Driver Setup
1. Find /webapps/jpetstore/WEB-INF/classes/properties/petstore.properties from your Tomcat directory. (c:\program files\apache\tomcat 5.0, for me)
2. Change the default (oracle) values to match the following:

   SimpleDriver=org.gjt.mm.mysql.Driver
   SimpleUrl=jdbc:mysql://localhost:3306/jpetstore
   SimpleUsername=jpetstore
   SimplePassword=ibatis9977
   	

3. Save it!
9. Test
1. Shutdown and restart your Tomcat Web Server by either stopping the Service or using the System Tray icon.
2. Once Tomcat has restarted, click here (link will open a new window): http://localhost:8080/jpetstore .
3. Have fun!

Troubleshooting

I figured I'd try to do things wrong and see what errors I got in case it happens to one of you. :)

• No action instance for path /shop/index could be created

Message: HTTP Status 500 - No action instance for path /shop/index could be
 created
Description: The server encountered an internal error (No action instance
 for path /shop/index could be created) that prevented it from fulfilling
 this request.
	

I got this error by deleting the JDBC driver from Tomcat's common/lib directory. If you see this error, follow the directions in Step 5, and then restart the Tomcat server.


• Error getting transaction

Unhandled Exception: com.ibatis.db.dao.DaoException: Error getting transaction.
Cause: java.sql.SQLException: Invalid authorization specification, message from
 server: "Access denied for user: 'jpetstore@localhost' (Using password: YES)"
 <---- Caused by: java.sql.SQLException: Invalid authorization specification,
 message from server: "Access denied for user: 'jpetstore@localhost' (Using
 password: YES)" ---->
	

I got this error by deleting the jpetstore@localhost user from MySQL. See Step 6.5.

Note: While porting the iBATIS JPetStore to use MySQL I had a big problem where I got this error even when I had clearly created a 'jpetstore' user. After trying a few things out, I found out you have to make the user as 'jpetstore@localhost' rather than 'jpetstore' in order for this to work. If anybody knows why this occurs, please let me know.