Home › Tutorials

Jspresso in 10 minutes

Installing the required tools

This is probably the longest part of this step-by-step introduction. Download and install the following 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.10 or 2.1). Install location referred below as ${MAVEN_HOME}.
  • the AT&T Graphviz graph visualization tool (2.17+). Install location referred below as ${GRAPHVIZ_HOME} only useful for documenting Spring beans through beandoc.
  • the Apache Tomcat servlet container (6.0+). Install location referred below as ${TOMCAT_HOME}.

Jspresso supports the use of the commercial Canoo ULC distributed GUI library (Jspresso 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 , Adobe's Flex and Swing front-ends will be available.

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

You must also increase the java heap space allocated to Maven :
on windows :

set MAVEN_OPTS=-Xmx512m (or set it as a user env variable)

on linux :

export MAVEN_OPTS=-Xmx512m (or set it as a user env variable)

 

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: ... -> jspresso-archetype (Jspresso Application Archetype (for 3.x))
2: ... -> jspresso-archetype (Jspresso Application Archetype (for 2.x))
Choose a number:  (1/2):
  • Select the Jspresso application archetype by typing "1". 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 : com.example.helloworld
Define value for artifactId: :
  • Type in the artifact id of your new project : helloworld
Define value for version:  1.0-SNAPSHOT: :
  • Confirm the default value.
Define value for package:  com.example.helloworld: :
  • Confirm the default value.

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

Confirm properties configuration:
jspressoVersion: 3.0.0
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: com.example.helloworld
artifactId: helloworld
version: 1.0-SNAPSHOT
package: com.example.helloworld
 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 property (only if you want to document your Spring beans with Maven site plugin) :

  • 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 helloworld 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.

  • Move to the new generated helloworld project directory and type :
  • If you have ULC installed (this will setup your local maven repository with the various ULC dependencies before packaging the complete webapp) :
mvn validate -Dulc.home=${ULC_HOME}
mvn package -Pulc
  • If you don't have ULC installed (this will package the webapp while ignoring all ULC/JNLP stuff) :
mvn package

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 :

helloworld/webapp/target/helloworld-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 helloworld/conf/jaas.config to ${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 properties).

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 linux, 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://localhost:8080/helloworld-webapp/wings/

For the Adobe's Flex version, point your browser at :

http://localhost:8080/helloworld-webapp/flex/

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

http://localhost:8080/helloworld-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.