Home › Tutorials

Jspresso in 10 minutes

Starting from release 2.2, it has never been easier to bootstrap and develop a new Jspresso powered application. Give us 10 minutes of your time and deliver your first Jspresso application in a few command lines.

Installing the required tools

This is probably the longest part of this step-by-step introduction. Download and install the following open source tools :

  • the Java Development Kit for your platform (JDK 6+). Install location referred below as ${JAVA_HOME}.
  • the Apache Maven project management tool (2.0.9+). Install location referred below as ${MAVEN_HOME}.
  • the Apache Ant build tool (1.7.1+). Install location referred below as ${ANT_HOME}.
  • the XDoclet 2 code generation engine (1.0.4+). Install location referred below as ${XDOCLET2_HOME}.
  • the AT&T Graphviz graph visualization tool (2.17+). Install location referred below as ${GRAPHVIZ_HOME}.
  • the Apache Tomcat servlet container (5.5+). Install location referred below as ${TOMCAT_HOME}.

Jspresso supports the use of the commercial Canoo ULC distributed GUI library (Jspresso 2.2 uses ULC 6.0.5). If you have purchased a license of ULC, install it (install location referred below as ${ULC_HOME}). Of course, you will still be able to build, package and run your project without ULC; in that case, only AJAX WingS and Swing front-ends will be available.

Configure Maven, Ant and Tomcat launch scripts to point to ${JAVA_HOME} and setup your path to include their "bin/" directories.

Generating the application project

Create a new empty directory to host your projects (e.g. "~/workspace"). This directory will be referred below as ${WORKSPACE}.

Move in ${WORKSPACE} and type the wollowing command :

mvn archetype:generate -DarchetypeCatalog=http://repository.jspresso.org/maven2/

Note: don't forget the slash ('/') at the end of the command line. Otherwise Maven will not succeed in downloading the archetype correctly.

This instructs Maven to go to the Jspresso Maven repository to look for application archetypes. The output should be something like :

[INFO] Scanning for projects...
...
Choose archetype:
1: http://repository.jspresso.org/maven2 -> jspresso-archetype (Jspresso Application Archetype)
Choose a number:  (1):

Select the Jspresso application archetype by typing "1" or just validating the default answer. It is now time to configure some important values in your project :

Define value for groupId: :

Type in the group id of your new project (e.g. "org.test.testapp"). This value will be referred below as ${GROUPID}.

Define value for artifactId: :

Type in the artifact id of your new project (e.g. "testapp"). This value will be referred below as ${ARTIFACTID}.

Define value for version:  1.0-SNAPSHOT: :

Type in the initial development version of your new project (e.g. "1.0-SNAPSHOT") or just validate the default. This value will be referred below as ${VERSION}.

Define value for package:  ${GROUP_ID}: :

Type in the root package of your new project (e.g. "org.test.testapp") or just validate the default. This value will be referred below as ${ROOT_PACKAGE}. Sometimes the root package mut be referenced by its path when loading resources. In this case, we will use ${ROOT_PACKAGE_AS_PATH}. For instance for a "org.test.testapp" package, its path form will be "org/test/testapp" (without leading slash).

Maven outputs the following to let you review the project settings :

Confirm properties configuration:
jspressoVersion: 2.2
xdoclet2Home: C:/envdev/xdoclet2
graphvizExecutable: C:/envdev/graphviz/bin/dot.exe
applicationDescription: Example Application Description
companyUrl: http://www.example.com
applicationName: Example Application
companyName: Example Company
siteDistributionUrl: file:///tmp/maven-site
groupId: org.test.testapp
artifactId: testapp
version: 1.0-SNAPSHOT
package: org.test.testapp
 Y: :

There are certainly default settings to change, so answer "N". Review all the questions and adapt the answers to your environment. Pay special attention to the following properties :

  • xdoclet2Home must point to ${XDOCLET2_HOME}
  • graphvizExecutable must point to ${GRAPHVIZ_HOME}/bin/dot[.exe]

Of course, you are free to change company name and URL, application name, and so on. Maven should re-output the property values and you can now validate ("Y") and launch the generation process. Wait for the "BUILD SUCCESSFUL" output. The archetype plugin will issue a bunch of warnings in the form of ${xxxx} is not a valid reference. You can safely ignore them. They are due to the fact that the maven archetype plugin tries to find a replacement value for each and every "${xxxx}" placeholder but some of them are to stay "as-is" in the final project and don't need any replacement.

You should now have a new directory ${WORKSPACE}/${ARTIFACTID} generated. This is the maven project directory of your application. Everything is properly configured for you to work, package, install and generate documentation.

Building and packaging the application

During this process, there are some instructions that will depend on the presence of the ULC commercial library. If you have not licensed ULC simply ignore them (or adapt the command lines). Every ULC-specific instructions are marked in green.

Move to the new generated project directory :

 cd ${WORKSPACE}/${ARTIFACTID}

and type :

  • If you have ULC installed :
mvn validate -Dulc.home=${ULC_HOME}
mvn package -Pulc

This will setup your local maven repository with the various ULC dependencies before packaging the complete webapp.

  • If you don't have ULC installed :
mvn package

This will package the webapp while ignoring all ULC/JNLP stuff.

This command may take some time to execute since Maven must download and install all the required plugins and dependencies in the machine local repository, so be patient and wait for the "BUILD SUCCESSFUL" output. Plugins and dependencies downloading is a one-time process since everything is now locally cached.

You should now have your webapp archive built and ready to be deployed. it is located here :

${WORKSPACE}/${ARTIFACTID}/webapp/target/${ARTIFACTID}-webapp.war

Deploying the application in the servlet container

The instructions below are given for Apache Tomcat. They should be easily ported to another application server.

Jspresso relies on JAAS for authentication. The application you've just packaged provides a development JAAS configuration file (without any required backend) that has to be registered in the application server.

Copy the ${WORKSPACE}/${ARTIFACTID}/conf/jaas.config file in the configuration directory of Tomcat : ${TOMCAT_HOME}/conf. If you already have some JAAS configuration somewhere else (for another application for instance), just complete the existing configuration with the content of the jaas.config file (don't hesitate to take a look at it since it provides a good place to vary the development user caracteristics).

The following java system property -Djava.security.auth.login.config=${TOMCAT_HOME}/conf/jaas.config has to be registered during the server startup. The standard way of doing this differs depending on the hosting platform. For instance, on windows, you will edit the ${TOMCAT_HOME}/bin/startup.bat script and complete it with :

set JAVA_OPTS=-Djava.security.auth.login.config=${TOMCAT_HOME}/conf/jaas.config

Under certain linux distributions (Debian for instance), the same configuration can be achieved by editting /etc/default/tomcat[version].

Once this is done, copy the webapp archive in the Tomcat deployment directory - ${TOMCAT_HOME}/webapps - and start Tomcat.

Your Jspresso application is now accessible, with a login of demo/demo (actually the values set in jaas.config).

For the AJAX WingS version, point your browser at :

http://[host]:8080/${ARTIFACTID}-webapp/login.html

For the ULC/JNLP version, point your browser at :

http://[host]:8080/${ARTIFACTID}-webapp/webstart/application.jnlp

Congratulations! You have created, packaged and deployed your first Jspresso powered application. It's rather minimalistic but all the layers are here and working together :

  • HSQLDB in-memory database
  • Hibernate
  • Spring
  • Swing, ULC and WingS
  • Binding, I18N, ...

If you give us a few more minutes, we will develop a small CRUD application. But don't forget that Jspresso is much, much more than a CRUD framework. Take a look at the documentation as well as the various screenshots and live demos to get a better understanding of it.