This section describes how to setup the project and start developing it.
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.
- Set the JAVA_HOME environment variable. Both Maven and JBoss need it.
- 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
- Eclipse 3.1+ from http://www.eclipse.org
- NetBeans 5+ from http://www.netbeans.org
- Subversion support is not that good yet, use a separate subversion client
- IntelliJ IDEA 5.1+ from http://www.jetbains.com
- Subversion is fully supported since IDEA 5
- 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)
- Poseidon 4+ community edition from http://www.gentleware.com
- 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
Main build command
Open your command line (CygWin, bash, DOS, ...) and run in the project root:
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
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.
There are 2 choices:
Use the Eclipse plugin for Maven to generate .project, ... (recommended for the moment)
- Ensure that you've followed the directions above and the execution of mvn install completed properly.
- 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.
- Install the Subclipse plugin if you haven't done so already.
- 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.
- 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.
- 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.
- 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.
- 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.
Install the maven 2 plugin for NetBeans referenced on http://maven.apache.org.
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
Just run the following class of the project spring-richclient-samples-simple:
Just run the following class of the project spring-richclient-petclinic-standalone:
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:
TODO NOTE: webstart doesn't work at this time, but will soon
Either configure them in your IDE or do:
Adding our code conventions to your favorite IDE
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.
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.
Generate the website
To generate the website simply do:
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:
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.