Developer Environment Setup

The following is a guide to get the MetPetDB development environment set up on your local machine.

First you must install the necessary tools and database software:

Tools and Resources

IMPORTANT: Avoid spaces like the plague. Do not place any of these tools in a file path that has spaces. So for Windows, installing to My Documents or Program Files is bad. While some of these may work fine under these circumstances, it will save a lot of grief if you just avoid it.

PostgreSQL (download:  Windows |  Linux | Mac)
The SQL database behind MetPetDB is PostgreSQL. Install the server according to the documented guidelines. However, do not check the box to install PostGIS as that will be done separately. Be sure to keep the password and username you provide in a readily accessible location as you will need this data again at a later time. Throughout the installation, use the default settings.

PostGIS (download:  Windows |  Linux | Mac)
To enable spatial operators (for geopositioning) MetPetDB uses the PostGIS database extension. The PostGIS installation procedure is fairly well documented in the PostGIS documentation itself . During the installation process, you will be given the chance to create a database, but you don’t have to worry about this stuff. We’ve got that covered, so just hang tight!

Mac users: PostGIS requires a few frameworks to be installed BEFORE you install PostGIS. They are packaged in disk images and are currently stored in the repository. Download and install them in this order: PROJ, GEOS.

Java Development Kit (JDK) ( download)
You do not need Java EE SDK, NetBeans, or JRE. A 1.5.x or later JDK is required to compile MetPetDB. A JRE is NOT sufficient for compiliation, as it does not include the Java compiler. To be sure you have the JDK, a folder should be created on your system that is named "jdk(Version#)".

Windows users: When you have installed Java Development Kit, return to the Environment Variables screen, then...

1. Under user variables, change PATH to be the address of the bin in the jdk.
2. In addition, create a new variable JAVA_HOME as a system variable and give it the address of the jdk folder.
3. Under Path in System Variables, add %JAVA_HOME%\bin.

Mac OS X 10.5 users: already installed.

Mac OS X 10.6 users: comes with jdk 1.6, but GWT currently requires jdk 1.5 for mac. Follow these instructions...

In the terminal:

Get the java 5 that was included in 10.5 "leopard" and unpack

 cd /tmp/
 curl -o java.1.5.0-leopard.tar.gz http://www.cs.washington.edu/homes/isdal/snow_leopard_workaround/java.1.5.0-leopard.tar.gz
 tar -xvzf java.1.5.0-leopard.tar.gz

Move it to your System java folder (password needed)

 sudo mv 1.5.0 /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0-leopard

Tell OS X that java 5 actually is java 5

 cd /System/Library/Frameworks/JavaVM.framework/Versions/
 sudo rm 1.5.0
 sudo ln -s 1.5.0-leopard 1.5.0
 sudo rm 1.5
 sudo ln -s 1.5.0 1.5

Eclipse IDE for Java Developers ( download)
Eclipse is the preferred IDE for development of this project. Be sure to install the  Subversive plugin to integrate Subversion into the Eclipse project files. More Eclipse plugins.
( Subclipse should also technically work, but has caused problems in the past.)

Google Web Toolkit (GWT 2.0.X) ( download)
The MetPetDB client side components must be translated from Java source code to HTML+JavaScript before they can be utilized by a browser. There are now two downloads required to get GWT 2.0.X working, the GWT SDK and the  GWT Eclipse Plugin. Note that because the plugin uses GWT 2.1.X, you will need to download version 2.0.X of the SDK and save it in a directory of you choice.

Apache Ant ( download Optional - included with Eclipse )
The MetPetDB build scripts use Apache Ant. Ant installation is just a matter of decompressing the binary distribution and adding the bin/ subdirectory to your PATH. To do this on a windows machine, right click My Computer and traverse the following. My Computer->Properties->Advanced->Environment Variables. Under System Variables, click Path. Select edit and then add a semi-colon and the address of the ant bin. See  this guide for editing the PATH in Mac OS X.

Apache Tomcat ( download Optional)
To run the MetPetDB server-side components, Java Servlets are used. To make use of these, Apache Tomcat 5.5.x is needed. Standard Tomcat installation instructions should be followed for your platform. It is usually just a matter of downloading the binary distribution and expanding it to a directory on your drive.

Installation Guide

After installing the tools and resources above, it's time to set up Eclipse.

Eclipse Setup

• With Eclipse open go to Window->Open Perspective->Other... and select SVN Repository Exploring
• Right click on the Left Pane (SVN Repository) and go to New->Repository Location
• Enter URL:  https://subversion.cs.rpi.edu/svn/metpetdb
  • Use your RPI CS account username and password to authenticate

Windows users troubleshooting: You might get the following error: "svn: Can't create tunnel: The system cannot find the file specified."

Download TortoiseSVN ( download) Set the following environment variable (by right-clicking on My Computer, Properties, Advanced, Environment Variables, New):-

    Variable name: SVN_SSH
    Variable value: C:\\Program Files\\TortoiseSVN\\bin\\TortoisePlink.exe

(The "\\" is very important, otherwise it won't work. Equally, you cannot use the plink.exe that comes with putty as that fires up a command shell window which is really annoying. The TortoisePlink?.exe is a windows implementation of plink that doesn't bring up any UI)

Restart eclipse and try again
If you are constantly being prompted to enter your password there is a workaround for that. There is more than one, here's the one I remember:

???

• Expand the newly create repository location, and also expand the trunk directory
• Right click on mpdb-client and select Checkout...
• Keep the default settings and click Finish
• Repeat steps for mpdb-common and mpdb-server
• Switch back to the Java perspective (Window->Open Perspective->Other... and select Java (Default))
  • You will see three newly created Projects (mpdb-client, mpdb-common, and mpdb-server) they will all have approximately infinity+1 errors
• Expand the Project mpdb-common
• Create a new document in the root of the project named build.properties
• Add to build.properties the following:

  gwt_home=[your path to the GWT SDK 2.0.X]
  postgis=[your path to postgis]
  DATABASE=[name you want the database to be]
  APPUSER=[name of the user you want for the database]
  APPPASS=[password of the above user]
  

As an example:

gwt_home=/home/anthony/development/gwt-linux
postgis=/usr/share/postgresql-8.2-postgis
DATABASE=mpdb_watera2
APPUSER=metpetwebtst
APPPASS=

{{{ Right click on build.xml and select Run As->Ant Build... Under Targets select all-eclipse and click Run This will generate the appropriate .classpath file for each of the projects }}} Currently broken. Steve distributed screenshots of his Eclipse Build Path settings. These can be found in an attachment at the bottom of the page and can be used as a guideline for setting up your project build paths.

• In order to do so right click on each project, select Properties, then choose the Java Build Path tab.
  • From here modify the contents of the Source, Projects and Libraries tabs such that they match the screenshots.
  • Make sure to include the exclusion filter "**/java_emu/**/*.java" in the source tabs where shown.
  • In addition to those shown, add gwt-recaptcha-1.0.0.Beta2.jar to the libraries for the client project.
  • Also note that your GWT Plugin will likely use version 2.1.X of the GWT SDK. If this is the case it will need to be configured to use an older version.
    • To do so select the GWT SDK Library and click Edit...
    • Then select the Configure SDKs... link. This will take you to a list of known SDKs.
    • Click Add... and navigate to the directory in which you saved version 2.0.X of the SDK.
    • You should then be able to select the correct version of the SDK
  • You will need to link the client project's source folder in the server project
    • In the server project's source select "Link Source..."
    • Navigate to the client folder's source folder and name the linked folder "client-src"
• Right click on each of the projects and select Refresh
  • All of the errors for the projects will magically disappear
• Navigate to mpdb-server/src
• Create a file called files.properties
  • This properties file contains the paths to where upload files are stored and it should contain the following: (see files.properties.base):

    fileUpload.path=/full/path/to/store/uploaded_files/
    images.path=/full/path/to/store/uploaded_images/ 
    

• Download the file 'hibernate.cfg.xml' (attached at the bottom of this page.)
  • Copy it to the edu/rpi/metpetdb/server/dao directory of your server project.
  • Edit the hibernate.connection.url, name and password fields to match your postgres login credentials.
• Your project should be ready to run. To do so first select the Client project, then navigate to Run->Run Configurations...
• Create a new configuration by double clicking on the Web Application item on the left. This will create a new configuration which you can name something like "mpdb-run"
• To run the project click the Run button. In the future you will be able to select this configuration from the drop down menu by the green run arrow. (It should also be the default in the future.)

Mac OS X 10.6 users: If you had to download jdk 1.5, then you need to tell eclipse to use it. In each project (mpdb-client, mpdb-common, mpdb-server) right click JRE System Library -> Properties. Select alternate JRE and find JVM 1.5 in the drop down. Click Okay.

Next, set up the database.

Database Setup

For this initialization to work properly, you must have the files lwpostgis.sql and spatial_ref_sys.sql in the directory specified by postgis= during Eclipse setup.

Postgis 1.4+: 'lwpostgis.sql' has been renamed 'postgis.sql'. Navigate to mpdb-server/build/schema and open recreate-database.sql. Replace 'lwpostgis.sql' with 'postgis.sql' and save.

• Start up psql (*NIX users can type the command in the terminal, Windows users can go to Start->Programs->PostgreSql->psql)

Mac Users: You will need to add the postgres bin folder to your $PATH variable. Open a terminal window and type...

   echo 'export PATH=/usr/local/pgsql/bin:$PATH' >> ~/.bash_profile

Reopen the terminal and it will be added to your $PATH.

Before using psql you will need to become the postgres user. To do so type..

   sudo su postgres

• Enter the password for the account you created when you installed PostgreSQL
• Change directory to mpdb-server/build/schema, An example of this is

  \cd C:/workspace/mpdb-server/build/schema 
  

• Execute \i recreate-database.sql
• Now change the directory to mpdb-server/build/schema/migrations
• Execute '\i 10_16_10.sql' and '\i 3_15_10.sql'

Troubleshooting for Mac

Safari 4.0.4 has a bug that causes hosted mode to crash. To fix this...

1. From  http://nightly.webkit.org/, download the current Mac OS X build
2. Open up the .dmg, then drag it to /Applications/.
3. In Eclipse, select Run->Run Configurations... from the menu.
4. On the left side, select mpdb-client.
5. Click the Environment tab.
6. Add variable:

Name: DYLD_FRAMEWORK_PATH Value: /Applications/WebKit.app/Contents/Frameworks/10.6

7. Save that [Append environment to native environment should already be selected].

Running the Project

• In Eclipse, Go to Run->Open Run Dialog...
• Select mpdb-server under Java Application and click Run
• Select mpdb-client under Java Application and click Run MetPetDB

Mac users: There is an additional argument needed to run. In Eclipse, Go to 'Run->Open Run Configurations...' For both mpdb-server and mpdb-client, Go to 'Arguments' and append -XstartOnFirstThread to the list of arguments.

Source Control

To keep your code up-to-date:

Getting the latest code

• In Eclipse, right click on the project name.
• Select Team->Synchronize With Repository.
  • This will bring up the Synchronize perspective.
• On this page, right click the project name and select Synchronize.
  • This will show you the changes that have occurred in the source code, it will not update the code nor commit any of your changes. You need to choose the Update... option to do that.

Committing the Code

• In Eclipse, right click on the project name. Select Team->Commit.
• This will bring up a view with check boxes next to the files you have modified.
• Place a comment in the top box describing the changes you made.
• Click OK to commit the changes.