Chapter 8. Developer Guide

8.1. Pre Requisites

The JTrac development environment uses Maven 2 only for dependency management and generating and deploying the JTrac
website hosted at SourceForge. Almost all other development actions (clean, compile etc) are fired through
a detailed Ant script that is able to use the dependency information managed by Maven. Using Maven ensures that
no binaries (JAR files) need to be checked into version control at all.

You can get some idea about the details and rationale of the custom Ant + Maven integration approach from
this blog post.

But if you are comfortable using Maven, the pom.xml is Maven 2 compliant which means that you can
directly build the war file without Ant.
You can even choose to use the maven-jetty-plugin by
uncommenting the section in pom.xml that declares this.

Although NetBeans is preferred by the JTrac developers, depending on an "IDE Neutral" Ant script
ensures that you would easily be able to use Eclipse (or any other IDE of your choice) without any problems.

If you get stuck or have any questions about setting up and getting started, feel free to use the
JTrac forums for help.

8.2. Check Prerequisites

Maven 2 should be in your "PATH". You can test this out by opening a command prompt and trying to run the
command "mvn". If this is set, you are ready to move to the next step.

8.3. Download / Extract Source

Download the source code from
SourceForge
and extract it to a convenient location. Note that the source code is a separate download from the main (binary)
and the file name will be of the form "jtrac-src-X.Y.Z.zip".

You could choose to check out the source code directly from the JTrac SourceForge Subversion repository.
The Subversion URL for the JTrac source code is as follows:

https://j-trac.svn.sourceforge.net/svnroot/j-trac/trunk/jtrac

If you are behind a corporate firewall that requires NTLM authentication, you can try a tool called
NTLMAPS to check out from Subversion.

If you are using Windows, we recommend TortoiseSVN
as a Subversion client.

8.4. Customize Ant Build Properties File

The downloaded source code should contain a sample "build.properties" file or you can look at the XML comment
provided at the top of "build.xml" for the structure. Actually the couple or so entries are optional and you will need
them only if you want to use Tomcat (instead of Jetty) or use the JMeter
script available for load-testing.

8.5. Generate Dependencies Properties File

Open a command prompt and change to the "jtrac" folder. Run the following command:

mvn antprops:generate

This step will not only download all the required JAR files (which may take time only for the first time),
but also generate a standard properties file that will contain all the information required for
the Ant build script to operate. The file generated is called "build-deps.properties"

Note that you need to perform this step every time the "pom.xml" file changes. This happens rarely
and typically when newer versions of JTrac dependencies (e.g. Spring and Hibernate) are available. Keep
watching for changes in the versions of JTrac dependencies or specifically changes to "pom.xml" to avoid
any problems.

If the command does not work, maybe you are not connected to the internet. Here's a tip that may help if you
are behind an HTTP proxy. This has been reported to work even when the proxy requires NTLM authentication.
You can append a parameter when running Maven commands as follows:

mvn antprops:generate -Dhttp.proxyHost=172.19.56.56

Note that if your proxy port is different from the default 80, you will have to add an "http.proxyPort"
parameter as well.

8.6. Import project into your IDE

If you are a NetBeans user you are ready to build and run JTrac! Just use the "Open Project"
option from the "File" menu, browse to and select the "jtrac" folder. You should be able to open it
as a valid NetBeans project.

If you want to use Eclipse, that's easy as well. First you have to run the following command and
Maven will then generate the Eclipse project descriptor files for you.

mvn eclipse:eclipse

That should create the ".project" and the ".classpath" files. Now its just a matter of
importing "Existing Project into Workspace" within Eclipse. Note that the Eclipse project descriptor
files also need to be re-generated when JTrac dependencies change, i.e. when "pom.xml" changes.
Make sure you do this also if you ever run "mvn antprops:generate".

For Eclipse to work with Maven 2, you have to have a classpath variable called "M2_REPO" set correctly.
Refer the Maven 2 documentation
for details on how to do this.

While debugging, if you would like to step through the source of dependencies as well, you can tell Maven
to download sources for dependent jar files. Note that source may not be available for some jars.

mvn eclipse:eclipse -DdownloadSources=true

8.7. Building And Running JTrac

You can explore all the Ant targets that are available. You can also try the "jetty-start"
Ant target straight away that will compile, create and deploy the exploded war as well as boot a Jetty server.
For NetBeans users, the "jetty-start" target is conveniently mapped to the "Run Main Project (F6)" shortcut,
once you make JTrac the "main project". Note that this Ant target is smart enough to detect if Jetty
is already running and will perform a shutdown if required before re-starting.

When starting with freshly checked-out source code, the Ant script may prompt you for a JTrac Version
and then create a "version.properties" file. This process is just to make the JTrac release process easier
so it does not really matter what you type. You would typically need to do this only once in development mode.

Maven has been configured to download the Jetty web server which drastically reduces the amount of
setup that you need to do in order to set up your development environment. Since JTrac creates
the HSQLDB database if required on startup, you do not need to worry about installing, configuring
and creating any database either.

If you want to use Apache Tomcat instead of Jetty, just have "build.properties" point to a valid Tomcat instance.
By now, you may have noticed that because of the
Ant script,
you don't even need a Tomcat or Jetty plugin in either NetBeans or Eclipse.

8.8. Adding a language translation for JTrac

JTrac has full internationalization (i18n) support and you can easily add a new language without re-compiling JTrac.
All you need to do is introduce a translated version of the existing "messages.properties" file into
the "/WEB-INF/classes" folder. Note that you will need to unzip the WAR file in order to add more files to it.

For example, if you need to add a translation into French, a file called "messages_fr.properties" should exist.
You can refer the list of Java locale codes
here. Note that country
specific locales are also supported, for example "fr_CA" means "French, Canada".

You can look at the existing translations e.g. "messages_de.properties" as examples. Note that
JTrac needs to be restarted for changes to the properties files to take effect. However,
switching the language for any user can easily be done anytime from the "Edit Your Profile" link on the
options screen and this takes effect the instant the user saves his profile.

You can use this nice open-source tool called PRBEditor
that really helps by showing the English and translated versions side by side on a single screen. It also
takes care of handling special characters.