Chapter 8. Developer Guide

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.

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.

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://sourceforge.net/p/j-trac/code/HEAD/tree/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.

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.

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.

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
                

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.

This is very easy and does not require any Java programming knowledge. If you unzip the file called "jtrac.war" the HTML files used by JTrac can be found in the folder: "jtrac/WEB-INF/classes/info/jtrac/wicket". All you need to do is edit 'BasePage.html' which is the common template used by all web-pages in the JTrac user-interface. You may want to also edit 'LoginPage.html' and 'LogoutPage.html' as well.

You can place any additional images you need such as a company logo at the top level or in "jtrac/resources" where all the other images used by JTrac are kept. JTrac uses a single CSS file called "jtrac.css" which is also in the "resources" folder. You can easily customize the fonts, colors and icons used across JTrac by just editing a single CSS file.

Recent versions of jTrac have a number of customization options built in under OPTIONS -> Manage Settings. There it's possible to change the top-left image, the header text, and the colors used throughout jTrac without having to jump through the hoops mentioned above, or having to know CSS.

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_en.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 also get the latest versions of the "messages_en.properties" as well as the available translations directly from version control at this url: https://sourceforge.net/p/j-trac/code/HEAD/tree/trunk/jtrac/src/main/resources/ Since these may change a lot, it is recommended that you check here as well before submitting a translation. We recommend that you submit translations as attachments on the JTrac patches tracker where we keep track of code contributions as well.