Saturday 13 August 2011

Introduction and setup instructions

I have been working on a project in my spare time to learn new tools and technologies.  It is a Java rest server stack using Jersey with a MySQL Database.   It has a Flex client as an example of how to communicate between a server and client. While working on this project I have learned so much from Blogs, Forums, books and technical documents, that I felt I needed to give back to the community.  So I released all the code I wrote as open source and I am writing this blog to describe how and why I created each section.
You can download the code for the server stack and the Flex client at 
I have given a large effort into following best practices and  design patterns, but as with everyone i am still learning. So if you see any areas we can improve this code please feel free to let me know. 

Now as a first step I will go though how to setup everything need to run the server stack. The instructions will be broken up into the next few blog posts. 

Tools we need to install

Make sure when you download these you get all 64 bit or all 32 bit. Mixing and matching doesn't always work. 
Below is the name and location of all the tools needed to run this server stack and the version that it was build and tested with 

Tool
Location
Built against version
Eclipse
Indigo
Tomcat
7.0.19
Maven
3.0.3
Java EE SDK
Java 6 Update 3
MySQL
Community Server 5.5.15 And Workbench 5.2.34
TortoiseSVN
1.6.16

There is lots of great information out there on how to install these tools, so I won't go into too many details. I will just cover the slightly more confusing parts.
- After installing Java make sure the environment variables are setup correctly. On Windows 7 you can type in "system" in the start menu, then select "system" under the control panel divider. Now select "Advanced system settings" on the right, then Environment Variables. 
Under the system variables, we need to make sure there is a - JAVA_HOME - system variable. This is the directory where the Java 6 SDK is installed. (default C:\Program Files\Java\jdk1.6.0_24) If there is not one click the new and use the Variable name: JAVA_HOME and Variable value: your install directory for the jdk.
We also need to update the - PATH - system variable to include the bin directory for java. (default ;%JAVA_HOME%\bin) If it is not there just add it to the end of the Variable value: when hitting edit
After installing tomcat, it is advisable to turn off the tomcat service since you don't need it always running. To do this type "services" in the start menu, Find Apache Tomcat 7 and right click to get properties. Now under start-up type set it to manual.
To install maven see the readme.txt that comes with maven.

Checking out the Google code project

The Google code project uses Subversion for its version control system. Wikipedia defines  version control as
"any practice that tracks and provides control over changes to source code. Software    developers sometimes use revision control software to maintain documentation and            configuration files as well as source code."
In our case we need to use TortoiseSVN as the client program to download the source code from the Google Subversion servers, this is called "checking out" the code.
To check out the code select the directory you want to download it to. Right click on the directory and select SVN Checkout in the context menu.
 Now we need to point SVN to the Google servers by entering the URL 
into the "URL of repository field". We can just use the defaults for the rest as seen below.

After clicking OK, it will download all the source code into the directory you selected. We now have all of the source code needed to compile and run the project.

Maven and eclipse

Maven is a powerful tool to make building and managing java projects easier. It is extremely quick and easy to get a basic project setup using maven, but for the more advanced user there is a lot of features and even more plugins to extend the functionality.
Maven uses a  Project Object Model (POM.xml) file to describe and build your project. This is a maven build file that defines all the dependencies and rules needed to compile this project.
The pom.xml is located under
            <repository>\server\rest\pom.xml
Open  a command window by running cmd.exe then navigate to the pom.xml file.
One feature of Maven is that we can have maven create the eclipse project for us. To create the eclipse project type
            mvn eclipse:eclipse -Dwtpversion=2.0
into the command window. 
This is going to create the eclipse project files such as .settings, .classpath, and .project. It is also going to download a lot of dependencies that we defined, so instead of having to hunt down dozens of jar libraries, we can tell maven what libraries we want, and it will download them for us.
Maven saves these library's to 
            C:\Users\<your login>\.m2\repository

Now open eclipse. When it asks for the workspace, enter in the directory you want to work in. This should not be the same directory you just build the project in, but the workspace directory should contain your project. So in my case my working directory is 
D:\java-rest\server and my project is in D:\java-rest\server\rest.
Once eclipse has opened we need to import our new project that we created with maven. So Select file->import->general->existing project into workspace. Select the directory with the .settings, .classpath, and .project files.

You probably have several build errors such as:
            Unbound classpath variable: 'M2_REPO/asm/asm/3.1/asm-3.1.jar'
This is because eclipse doesn't know where maven downloaded these jar files to. 
So we need to add maven integration with eclipse so we can automatically launch maven builds from eclipse. For this we will use a eclipse plug-in M2E
Luckily eclipse has a great plug-in architecture that makes it extremely easy download and install plugins directly from eclipse. 
To install plugins we need to go to help->install new software then paste in
into the "works with:" field.


If you want to save this site you can click add then give it a name so you can remember it later.
Click ok and wait for it to download the packages. then click the check box and click next. Finish the install.
Now we need to install the maven wtp for eclipse plugin -
Click the window -> preferences -> maven -> discovery ->open catalog.
Find and select the m2e-wtp plugin to check it off and click finish to install it. 
After these steps we have integrated maven into eclipse but we still need to tell eclipse that this specific project is a maven project. To convert the project to a maven project by right clicking on your project then configure-> convert to maven project


(above picture is skipping some menu items at the black bar to make the list shorter)

*Update
 - It looks like the m2e-wtp plugin is no longer available though the m2e catalog. But you can still install it using the install software method. With the same install instructions as we used to install m2e add the link to the help->install new software.
Updates at:

http://download.jboss.org/jbosstools/updates/m2eclipse-wtp/
                                or 
http://m2eclipse.sonatype.org/sites/m2e-extras

Tomcat eclipse integration

Now we need to add the tomcat server to eclipse:
A good blog post about this is here
First we need to make sure that the server tab is showing in eclipse. Select 
eclipse -> window-> show view-> servers or window-> show view-> other -> find the servers.
Now in the server view right click and select new server.
Select the Apache tomcat 7 server.

Using the default settings above should be fine.
In the next step you need to tell eclipse where Apache is installed to. Under Tomcat installation directory click "Browse.." and navigate to the directory you installed tomcat. For me it was
           

Now click next. Now we can tell tomcat what resources to run. The resources is our rest application. So click the "rest" resource and select add, then click finish.



To test right click on the server and select start.
If you get an error saying the port 8080 is already in use you need to make sure that the tomcat service isn't running. To stop the service run administrative tools from the start menu then select services. Find the Apache Tomcat service and stop it. Also set it to manual start-up, since this is your dev machine you don't need it to always be running. Eclipse will launch it, when you start debugging your project.

MySQL setup

Now we need to setup  MySQL, first we are going to create a user for the java rest stack to connect to MySQL with. Select Server Administration, by double clicking your DB you setup.


Under security click on "Users and Privileges" then to create an account add account on the bottom of the page.
Give them a name and password and remember them, we will need them shortly. When done select apply. This will create a new user in the MySQL.user table, but it will not give the new user any privileges. To give privileges we select "Schema Privileges" tab and highlight the new user. Then click the "Add Entry..." button, use the default settings and select ok. 
I gave the user SELECT, INSERT, UPDATE, DELETE, EXECUTE, SHOW, CREATE TEMPORARY TABLES and LOCK TABLES privileges. 

This is so they can manipulate the date in the tables, but do not have the ability to change the tables structure (such as ALTER or DROP). That isn't to say that a user can't destroy a database with the UPDATE ability, it is just harder.
When ready save the changes.
*Note that these settings are intended for local use in a tutorial, for a production database you would restrict the user even more.

Now we need to build the DB, that the rest server will use. Go back to the main page and select your DB under SQL Development.
Open the provided SQL files and execute them in the following order. They need to be in this order because some of the tables have dependencies on other tables. (ie one table has a foreign key constraint that references a primary key of a different table. )
1.      createdb.sql
2.      customer.sql
3.      role.sql
4.      customerRoles.sql
5.      session.sql
6.      ServerConfigTypes.sql
7.      serverConfig.sql
8.      createCustomers.sql

Now we need to setup the the rest server stack so it can communicate with mysql db to save our customers in.
The java file com.cred.industries.platform.database.DBConfig it stores the config information we need to connect to the SQL database. Usually it will load the config values from an xml file
            scr/main/resources/dbconfig.xml
But it is also hard-coded with some setup values. (I could not figure out how to get it to load the xml file when running unit tests.)  Change the DBUserName and DBPassword in both the .java and .xml file, to match the names of the user you just created in MySQL. You should not use the default setup, as they are not secure user names and passwords.

Congratulations, you should now have a working rest server stack. To test it either use the Flex client or run the unit tests under
            com.cred.industries.platform.test.CustomerTest
To do this, click on the debug drop-down and select CustomerTest unit test in eclipse.