Development setup

This section describes how to setup the project and start developing it.

Installation

Download and install the following technologies:

  • Sun JDK 1.5+ from http://java.sun.com (or from a Linux repository)
    • Set the JAVA_HOME environment variable. Both Maven and JBoss need it.

      On Linux open /etc/profile or ~/.bash_profile and add export JAVAHOME=... . The JDK might be under /usr/lib/sun-jdk-1.x.x . On Windows open Control Panel/System/Advanced/Environment Variables . The JDK will probably be under C:\Program Files\java\jdk1.x.x .

    • NOTE: Most of Spring-richclient can be run in Java 1.4 (except the tiger module and the petclinic sample), but it requires a 1.5+ JDK to build.
  • Maven 2+ from http://maven.apache.org
    • Set the M2_HOME environment variable.
    • Adjust the PATH environment variable to add ;$M2_HOME/bin (Linux) or ;%M2_HOME%\bin (Windows)
    • On Windows, the use of cygwin (with OpenSSH and Subversion) from http://www.cygwin.com to run maven is required for very advanced functionality (ssh repository deploy, ...)
  • One Java IDE (see below for configuration) with Subversion support
  • One separate Subversion client (optional if already supported in the IDE) It's possible and even handy to combine multiple Subversion clients.
  • One UML tool (optional)
  • One relational database (only required for petclinic)
    • HSQLDB in memory (already included in dependencies, no need to install)
    • MySQL server 5+ from http://www.mysql.org with
      • MySQL Query browser
      • MySQL Administrator
  • One J2EE 1.4+ application server (only required for petclinic standapart)

Getting the sources

See the source repository .

Building

Main build command

Open your command line (CygWin, bash, DOS, ...) and run in the project root:

mvn install

This builds the project and installs it into your local repository.

NOTE: The first time you run maven it will download all dependencies and cache them in your local repository in ~/.m2/repository , and it may not work the first time. If you have a bad connection to Ibiblio (Maven's default repository), you may have to execute this command a bunch of times (5 or more) until maven finally gets all the dependencies downloaded, try switching to a mirror of Ibiblio (see developer FAQ). Ignoring the multiple runs, the initial download of all these files will take a while. Run it again afterwards to see how fast it really is. Then take a look at the faq.html to run it even faster.

Once a multiproject install has been run, it's possible (not required) to build a single module with the same command in a module root.

Other build commands

mvn clean           Deletes all the generated files
mvn compile         Compiles the code
mvn test            Tests the code
mvn package         Generates the jar
mvn install         Copies the artifacts(jar, war, ...) to your local repo
mvn site            Generates the website

Build result

Take a look in the target directory in the project root and every module. You 'll find the module jar there, test reports and the website if you've generated it.

Create a single full jar (not recommended)

The project is moduralized, so it's possible to declare detailed dependencies. However, it might be easier for you to start out with a one single full jar. You can do this using the extra full module, which merges all other modules.

In the full module directory, run mvn install and take a look at the target directory.

It's highly recommended to depend on the seperate modules jar instead of the full jar.

Common pitfall: the full jar does not include spring binding or modules: don't forget them on your classpath.

Configuring your favorite IDE

Maven can do this for you.

Eclipse

There are 2 choices:

Use the Eclipse plugin for Maven to generate .project, ... (recommended for the moment)

  1. Ensure that you've followed the directions above and the execution of mvn install completed properly.
  2. Run in the root of the project mvn eclipse:eclipse . This command automatically makes use of the eclipse plugin in Maven 2 . It generates all the files necessary to define the projects for eclipse. If you also want the sources of the dependencies, do mvn -Declipse.downloadSources=true eclipse:eclipse instead.
  3. Install the Subclipse plugin if you haven't done so already.
  4. Import all existing projects found under the root of the project. Open the import wizard and select Import existing projects into workspace . Choose the root directory of the project and you should see 15 projects displayed. They will be named
        spring-richclient-archetype
    spring-richclient-binding
    spring-richclient-core
    spring-richclient-form
    spring-richclient-petclinic-business
    spring-richclient-petclinic-client
    spring-richclient-petclinic-common
    spring-richclient-petclinic-gui
    spring-richclient-petclinic-server
    spring-richclient-petclinic-standalone
    spring-richclient-resources
    spring-richclient-sandbox
    spring-richclient-samples-simple
    spring-richclient-support
    spring-richclient-tiger

    All the dependent libraries, source directories, etc. have already been configured.

  5. Set the M2_REPO variable. This is required because the .classpath files generated by mvn eclipse:eclipse reference the M2_REPO variable in the classpath entries.

    Open the window Window >Preferences .
    open the item Java >Build Path >Classpath variables .
    Add the new variable M2_REPO with the value of the folder USER_HOME/.m2/repository , for example C:/Documents and Settings/ge0ffrey/.m2/repository .

  6. Enable Subversion (if you haven't checked out with Subclipse): Right-click on each project and open Team >Share... . This may not be necessary since recent versions of eclipse will automatically enable subversion during the project import.
  7. Until the Maven plugin for Eclipse works properly, you will probably want to configure some external tools to perform maven operations from within eclipse (like you do with ant projects).

    Open External Tools...
    Add a new Program configuration
    On the Main tab, set the Location to M2_HOME\bin\mvn.bat for example D:\Tools\maven-2.0.2\bin\mvn.bat
    Set the Working directory to the project root directory.
    Set the arguments as needed for the command you want to run.
    If you don't have an M2_HOME environment variable setup, then you need to add it on the Environment tab.

  8. NOTE: This solution currently doesn't show you all files due to a limitation of Eclipse: Eclipse does not allow a project folder in a project folder. (There is an issue at eclipse.org for this.) Therefore the direct project root, samples root and petclinic root content isn't shown. This includes the multiproject pom.xml (very important!) and the site apt files. One way to fix this partually is to manually make a module of the /src directory under the root project, so you can at least edit the site apt files.

Using the plugin for Eclipse - THIS IS NOT RECOMMENDED AT THIS TIME

Install the maven 2 plugin for Eclipse referenced on http://maven.apache.org .

NOTE: This solution is untested (actually it has been tested and it broke things pretty badly).

Warning: Do not install a mevenide for maven 1 plugin, they do not work for Maven 2.

NetBeans

Install the maven 2 plugin for NetBeans referenced on http://maven.apache.org .

IntelliJ IDEA

Run in the root of the project mvn idea:idea . This command automatically makes use of the idea plugin in Maven 2 .

Open the ipr generated in the root of the project. All the dependend libraries, source directories, ... will be configured.

Enable Subversion (if you haven't checked out with IntelliJ): Open File >Settings >Project >Version Control . Select Subversion as version control.

Delete the module spring-richclient-archeypte or just unset it's java source dirs, so you can build the entire project with Intellij too.

Maven 2 versus your favorite IDE

After your IDE is configured with maven 2, you 'll use Maven 2 less frequently.

You 'll use your IDE to:

  • Compile and run an application or a specific testcase
  • SCM update or commit

However, Continuum will use Maven 2 every night to:

  • SCM update and clean
  • Compile and run every single testcase
  • Build and deploy snapshots
  • Generate and deploy the site

Running the samples

Simple

Just run the following class of the project spring-richclient-samples-simple :

org.springframework.richclient.samples.simple.app.SimpleApp

Petclinic

Standalone

Just run the following class of the project spring-richclient-petclinic-standalone :

org.springframework.richclient.samples.petclinic.PetClinicStandalone

Standapart (client-server)

Do a mvn install and deploy the war to a J2EE server:

cp samples/petclinic/server/target/spring-richclient-petclinic-server-<version>-SNAPSHOT.war /
<tomcat-home>/webapps/petclinic-server.war OR <jboss-home>/server/default/deploy/petclinic-server.war

TODO: the war's name should not define it's URL

Then run the following class of the project spring-richclient-petclinic-client :

org.springframework.richclient.samples.petclinic.PetClinicClientServer

TODO NOTE: webstart doesn't work at this time, but will soon

Running testcases

Either configure them in your IDE or do:

mvn test

Adding our code conventions to your favorite IDE

Eclipse

Open the menu Window <Preferences...>, then the item Java <Code Style><Formatter> and import the Eclipse file from the bottom of Spring's conventions page .

Note: You can also set the conventions specifically only for the spring-richclient projects, so your other Eclipse projects still use your original code conventions.

NetBeans

TODO

IntelliJ IDEA

Copy the IntelliJ IDEA file from the bottom of Spring's conventions page into the directory USER_HOME/.IntelliJIdea60/config/codestyles .

Open the menu File <Settings...>, then Project or Global Code Style and select the Spring conventions .

Website

Generate the website

To generate the website simply do:

mvn site

Then take a look at target/site/index.html .

To change the site content, take a look at src/site/apt .

Deploy the website

Create the file USER_HOME/.m2/settings.xml and add the following content:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <!-- ... -->
    </mirrors>
    <servers>
        <server>
            <id>shell.sourceforge.net</id>
            <username>xxx</username>
            <password>xxx</password>
            <filePermissions>775</filePermissions>
            <directoryPermissions>775</directoryPermissions>
        </server>
    </servers>
    <profiles>
        <!-- ... -->
    </profiles>
</settings>

It's important to set filePermissions and directoryPermissions correctly, otherwise you 'll make it impossible for other project-members to deploy the site.

Note: this configuration will also be reused when deploying artifacts to our remove maven repository.

Test if you can access the SF shell:

ssh xxx@shell.sourceforge.net

This probably won't work and you 'll need to create a private key at ~/.ssh/id_rsa first and log in to SF's website and paste your public key in their webform. Afther that it should work.

Now run:

mvn site-deploy