AZGS Logo

Modifying the Geoportal source code for the USGIN project is a team based effort.  Managing a project like this requires each user/programmer having the right tools and using the appropriate workflow so that one programmer does not overwrite another programmer's work.  This document describes project workspace setup and project workflow.

Key Terms

Resources

I strongly recommend going through this tutorial (http://ant.apache.org/manual/tutorial-HelloWorldWithAnt.html) to get a great introduction to using Apache Ant and Tomcat.

Part 1 - Project Workspace Setup

Text Editor
You will need to install a text editor like notepad++.

Command Tool
I like Cygwin (www.cygwin.com), which is a command line tool for Windows, but has a Unix based toolset.  However, the DOS command line will work.  See this link for Cygwin installation instructions.

Install and configure Java
Java needs to be installed on the system.  Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html and download the latest version of the Java Development Kit (JDK).
The JDK is an executable program and needs to be run with administrator priviledges.  The installation process will make the command line "java" and "javac" apps available at the command line.  The installation process should also make the JDK accessible on the system's path.

Install and configure Ant
Download a copy of Apache Ant from http://ant.apache.org/.  The Apache Ant build tool does not have an installation executable.  You will need to extract Apache Ant to your hard drive and make sure that the path to <Apache Ant Install Location>\bin is on the system's path environment variable.  Test to see if ant is configured propertly by typing "ant -help" at the command line.  If you see output describing switches and parameters for using ant then ant is installed correctly.  More instructions here for installing Apache Ant.

Install and configure Git
Download portable git from http://code.google.com/p/msysgit/downloads/detail?name=PortableGit-1.7.4-preview20110204.7z&can=2&q=
and open the file and extract the main folder to a location on your computer.  You will have to add the portable git root path and portable git bin path to your system path.

After git is installed you need to set the global user name and email address.  Set both of those by typing the following lines at the command line substituting the user name and email address you want to use for your git account..

git config --global user.name "Tekkub"
git config --global user.email "tekkub@gmail.com"

Install and configure Apache Tomcat
Download Apache Tomcat from http://tomcat.apache.org/download-60.cgi
Extract Tomcat from the downloaded archive and save to your hard drive.
Add the <Tomcat Install Path>/bin to you system's path environment variable.
Create a new environment variable named "CATALINA_HOME" and set its value to the <Tomcat Install Path>.
To test if Tomcat is running properly open the DOS command line shell and type "startup.bat".  You should see a window popup that will show messages from Tomcat as it is starting.  Next, open your web-browser and navigate to "http://localhost:8080".
Apache Ant needs the catalina-ant.jar file provided by Apache Tomcat.  Copy <Apache Tomcat Home>/lib/catalina-ant.jar to <Apache Ant Home>/lib.

If the server is running properly you should see a screen similar to the following:

See this link for more instructions on how to install Apache Tomcat.

Part 2 - Workflow

Workflow is dependent on Part 1 of this document.  Whether you are editing Java source code or ISO xml files, project work flow can be done using the following steps.

1. Using git to checkout a copy of the Geoportal source code from the source code repository:

Access the operating system command line using Cygwin or Cmd

Navigate to the workspace where you want to store the geoportal project's source code (e.g., cd c:\workspace or cd c:\Users\<Your user name>\workspace)

Type: git clone file:////SERVER3/DevelopmentDocs/gitRepository/geoportal

Confirm that a new folder named "geoportal" exists in your worksapce by typing "dir geoportal".  If the command lists files then the geoportal source code has been cloned.

You should only have to do this step once.

The cloned version of the project has a file called ajc.properties.  This file should be renamed to local.properties and you should edit the variables/settings in the file to match your computer's configuration.  A copy of ajc.properties is also attached to this blog entry.

2. Create a working branch.

Branches make it possible to work on the project source code without having to worry about making changes that can't be fixed.  For example, if you have spent three hours working on a branch only to find out that that there is a flaw somewhere that you can't fix or find then you can delete the branch and start your day's work over again with out affecting the original source code.  Think of the process as making a photocopy of a document, writing a bunch of changes on the photocopy and finding those changes to be incorrect.  The photocopy can be thrown away and the original document can be photocopied again so you can re-start the work.

To make a branch on the cloned repository (see step 1) type:

git checkout -b <branch name>, where <branch name> can be any name you like.  I use my computer user name "acatejr".

e.g. git checkout -b acatejr

If the command executes successfully then git will display a message about switching to the new branch.  If the git returns a message stating that the branch already exists then type git branch <branch name>.

You can determine which branch you are working on by typing the command "git status".  This will list all branches with an asterisk next to the current branch.

3. Source code or xml file changes

Now that you have created a branch and have set the git working environment so you are working on that branch you can make edits to source code files (i.e., java, jsp) and/or xml files (i.e., ISO definition and ISO template files.

4. Testing changes

After making a changes you need to test them in a working copy of the web application.  Assuming you followed the steps in part 1 you now have to start Apache Tomcat by typing: startup.bat at the command line.  Starting Tomcat this way will cause another command line window to open and you will see Tomcat display messages to that window.  You only have to run startup.bat once.  Iterative changes to code only require that you tell Tomcat to reload the web application you are working on.  Sometimes Tomcat can use up all virtual rmemory and that may require a Tomcat restart (type shutdown.bat followed by startup.bat).

Optional, Once Tomcat has started you can verify tht it is running by using your browser to navigate to http://localhost:8080  This tells the browser to access the web server (Tomcat) running on your computer listening on port 8080.  Tomcat uses the port 8080 as its default port.  You can change the port number by editing <TOMCAT_INSTALL>\confg/server.xml file and changing the section:

<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />

Ports can be thought of as ears.  A computer can have many ears...

Type ant compile package - this compiles the Java source code and packages the source code and web content related files into a web application folder.

Type ant reload - this tells Apache Tomcat to reload the web application so that it is using the changes you have implemented.

You can test your changes by browsing to the desired location at http://localhost:8080/geoportal (Geoportal's home page).

5. Saving Changes to the Repository

Once you are done making and testing changes to the geoportal source code you need to merge your work with the repository that you cloned the project from.

Commit your work: git commit -a -m "A log message to document my changes"

Change to back to the master branch: git checkout master

Merge the branch you created with the master repository: merge master <branch name> - substitute your branch name

Push your work to the master repository: git push origin master

Remove the branch you created: git branch -d <branch name> - substitute your branch name

Stop Tomcat by typing shutdown.bat at the command line.

6. Wash, Rinse, Repeat

You do not have to clone the project after you clone it the first time.  However, periodically you will may need to update the source code you have in your clone project by typing "git pull".  This will pull changes others have made to the source code into your copy of the project.

You should only have to repeat steps 3 through 5 in order to make more changes to the application.

7. So, you are done editing, testing and are ready to deploy the application to Debug.  Well, hold onto your hat.

       The first step is to prepare the application for deployment onto the Debug server.  Do this by typing "ant clean compile debug.package war"

Using your web browser load the http://debug.usgin.org:8080/manager/html Tomcat Admin url.

A list of installed web applications should appear in a section of the web page called "Applications".

If "Geoportal" exists in that list click the "Undeploy" link in the same row as the geoportal application.

Scroll down to the section labelled "War file to deploy" and click the "Browse" button.

Browse to and select the war file you created.

Click the "Deploy" button.

If all goes well the geoportal application should be up and running.

8. An alternative to Step 7

A less reliable alternative is to type "ant debug.deploy"

This alternative combines all of the steps in step 7, but may be less reliable due to network connections.

Resources

Files: 

build.xml

Files: 

ajc.properties