Importing the HR sample application in Eclipse

In this trail, we will explain step by step how to set-up a brand new Jspresso project in Eclipse. We will use the latest Eclipse IDE for Java EE Developers (Ganymede 3.4.2 as of this writing). The objective is to have a fully configured Eclipse project with the HR sample application and the different launch configurations.

We will :

  • Generate the Jspresso application project
  • Prepare Eclipse for importing the project
  • Import the project and its launch configurations
  • Open Spring IDE
  • Import the HR sample application sources into the project

Initial project generation

  • Move to your existing Eclipse workspace or create a new one.
Define value for groupId: : org.jspresso.hrsample
Define value for artifactId: : hrsample
Define value for version:  1.0-SNAPSHOT: :
Define value for package:  org.jspresso.hrsample: :
Confirm properties configuration:
jspressoVersion: 2.2
xdoclet2Home: [your path to xDoclet2]
graphvizExecutable: [your path to the GraphViz dot executable]
applicationDescription: Example Application Description
companyUrl: http://www.example.com
applicationName: Example Application
companyName: Example Company
siteDistributionUrl: file:///tmp/maven-site
groupId: org.jspresso.hrsample
artifactId: hrsample
version: 1.0-SNAPSHOT
package: org.jspresso.hrsample
  • Move to the generated project directory ("hrsample") and issue (if you have not already done so) :
mvn package

All your project dependencies are now available locallly in your local Maven repository and your project is ready to be integrated in Eclipse with most of the Eclipse configuration already there.

Preparing Eclipse

There are a few steps to walk in order to propare your Eclipse workspace for a Jspresso project.

  • Define a path variable that points to your Eclipse workspace :
"Window" -> "Preferences" -> "General" -> "Workspace" -> "Link Resources"
Click "New..."
"Name": WORKSPACE_ABSOLUTE_PATH
"Location": [the absolute location of your Eclipse workspace folder, e.g. "/workspace"]
  • Define a classpath variable that points to your Maven2 local repository (usually ${USER_HOME}/.m2/repository) :
"Window" -> "Preferences" -> "Java" -> "Build Path" -> "Classpath Variables"
Click "New..."
"Name": M2_REPO
"Path": [the absolute location of your Maven2 local repository, e.g. "~/.m2/repository"]
  • Configure the "Apache Tomcat v6.0" server runtime environment :
"Window" -> "Preferences" -> "Server" -> "Runtime Environments"
Click "Add..."
Select "Apache" -> "Tomcat v6.0"
Click "Next >"
"Name": Apache Tomcat v6.0
"Tomcat installation directory": [your Tomcat 6 installation directory]
Click "Finish"
  • Open the "Java EE" perspective :
"Window" -> "Open Perspective" -> "Other..." -> "Java EE"
  • The next step is to create the Apache Tomcat launch configuration :
Select the "Server" view (you should have it automatically in the Java EE eclipse perspective)
Right click
Select "New" -> "Server"
Select "Tomcat v6.0 Server"
Click "Finish"
  • And finally configure its launch configuration to point to the JAAS configuration of our Jspresso projects :
Double-click on the server you have just created
Click on the "Open launch configuration" hyperlink
Select the arguments tab
in the "VM arguments" text area, add (keep ${project_loc} as is, it's a built-in variable):
-Djava.security.auth.login.config=${project_loc}/conf/jaas.config

Importing the generated project and its launch configurations

When generating the project, the Jspresso archetype configured all the needed Eclipse files.

  • Import the generated project :
"File" -> "Import..." -> "General" -> "Existing Projects into Workspace"
Click "Next >"
"Select root directory": [your project root folder]
Click "Finish"
  • Import the launch configurations :
"File" -> "Import..." -> "Run/Debug" -> "Launch Configurations"
Click "Next >"
"From Directory": [your project root folder]/launches
Check "launches"
Select all available launch configurations
Click "Finish"

Everything should set-up correctly now. You can either launch your Jspresso application :

  • with a Swing frontend, with or without test data: just start one of the launch configurations you've previously imported. The Swing version of the application relies on a 2-tier architecture that is really useful during the development phase.
  • with an AJAX WingS front-end : just right click on your project root in the "Project Explorer" view and choose "Run As" -> "Run on Server", select your configured Tomcat 6 server configuration and click "Finish". You should have the eclipse browser view opening and targetting at "http://localhost:8080/hrsample-webapp/". If your Tomcat configuration allows for listing directories (forbidden by default), you can click "login.html" to go to the login page. If the displayed page is blank, just add "login.html" in the browser address bar. To allow Tomcat for listing directories (which is somehow useful in development), open ${TOMCAT_HOME}/conf/web.xml and search for "<param-name>listings</param-name>". Set a value of "true" for this servlet parameter.

The third GUI channel Jspresso supports (Canoo ULC) is not discussed here.

Opening Spring IDE

Jspresso relies on the Spring dependency injection container for the assembling the application. Wiring the descriptor beans may become a tedious task if not supported by an effficient tool (quick navigation between beans, navigation from a bean definition to its java source, auto-completion, ...). Hopefully, SpringSource publishes the Spring IDE eclipse plugin that should come bundled with "Eclipse for Java EE" distribution. If not follow the installation instructions given here.

Your Jspresso project comes pre-configured for Spring IDE. The only thing you have to do is bring the Spring Explorer view to your Eclipse perspective ("Window" -> "Show View" -> "Other..." -> "Spring" -> "Spring Explorer") and the project should be pre-installed in it.

Adding the HR Sample sources to the eclipse project

From version 1.2, the HR sample application source distribution is fully compliant with the files naming conventions taken in the archetype project. Importing the sources in the project is really easy :

  • Download and uncompress the source distribution of the HR sample application in a separate temporary directory (e.g. /tmp)
  • Copy the "java" and "resources" directories located in "hrsample-${version}/hrsample-core/main" into your existing "core/src/main" project folder. This will override the default generated sources.
  • Refresh your Eclipse project (select your project in Eclipse and hit "F5").

You can now test-drive the HR Sample webapp in Swing and AJAX as described above.

Working with the project

The eclipse project generated by the Jspresso archetype uses dependencies directly from the maven build directory and especially from ${WORKSPACE}/${ARTIFACTID}/webapp/target/${ARTIFACTID}-webapp/WEB-INF/lib. This directory contains not only the project dependencies but the jars of the project itself. For Eclipse to work correctly with it, you must delete the maven generated project jars from this folder :

  • delete ${ARTIFACTID}-*.jar

For a more detailed explanation of why this is necessary, please refer to this post in the forum.