Chapter 7. Development Processes

In this chapter we'll cover how we develop Spring Surf, and how you can check it out and get involved.

7.1. Setting Up for Development

We'll assume you typed the following to checkout Surf (if not, adjust the paths in the following instructions accordingly):

mkdir ~/spring-surf
cd ~/spring-surf
svn co

Those with commit rights should use the following SVN URL instead:

svn co

7.2. Building the Surf Platform Using Maven

Once your Spring Surf source tree is in place, you can build the platform by simply using Maven.

Make sure you have the following environment variable set:

export MAVEN_OPTS=-Xmx1024M -XX:MaxPermSize=512m

And then simply run:

mvn install

The following modules will be built:

  • Spring Web Scripts (jar)
  • Spring Web Scripts API (jar)
  • Spring Web Scripts Application (war)
  • Spring Web Scripts Test Application (war)
  • Spring Surf (jar)
  • Spring Surf API (jar)
  • Spring Surf Application (war)
  • Spring Surf Test Application (war)
  • Spring Surf Studio (jar)
  • Spring Surf Studio Application (war)
  • Spring Surf Roo Addon (zip/jar)
  • Spring Surf STS Addon (jar)
  • Spring Surf QuickStart Sample Application (war)
  • Spring Surf PetClinic Sample Application (war)
  • Spring Surf Spring Travel Sample Application (war)

7.3. Developing within Eclipse

The Spring Surf development team uses SpringSource Tool Suite to develop Surf. SpringSource Tool Suite (STS) which is SpringSource's free Eclipse IDE. While you can use any IDE at all, these instructions assume you're using STS. The main difference to be aware of is STS has setup the M2_REPO variable correctly, and thus the Maven paths work out of the box. You can setup M2_REPO manually within a normal Eclipse if you wish; just use Window > Preferences > Java > Build Path > Classpath Variables and set M2_REPO to the ~/.m2/repository directory.

To get started, change to the directory where you checked out Surf.

cd ~/spring-surf

You need to instruct Maven to produce .classpath and .project files for Eclipse. Let's run a clean and also tell Eclipse to generate these files for us. We'll also do a compile while we're at it.

mvn clean eclipse:clean eclipse:eclipse compile

You should now be able to import the projects into SpringSource Tool Suite. Click File > Import > Existing Projects into Workspace, and select the same directory as where you ran the "mvn" command from.

Several Spring Surf and Spring Web Scripts files will be listed. At this stage you're free to open any class and get to work!

7.4. Integrated Tomcat Testing

The default parent pom for the Spring Surf project has been configured with a Maven Tomcat Plugin that makes it simply to perform command line deployment of web applications. This is useful for building your Surf applications and deploying them to a Tomcat instance for debugging purposes.

The ideal Tomcat instance for use in this scenario is provided by the STS Integrated Tomcat server. Within STS, click Window -> Show View -> Servers and you'll see that STS has been preconfigured with several servers - one of which is the STS Integrated Tomcat server.

The ideal Tomcat instance for use in this scenario is provided by the STS Integrated Tomcat server. Within STS, click Window -> Show View -> Servers and you'll see that STS has been preconfigured with several servers - one of which is the STS Integrated Tomcat server.

If you start this server, it will bind to http://localhost:8080 and will be available to service the outside world.

To utilize deployment to this server, modify the tomcat-users.xml file under the "Servers" folder in the left-hand project pane for the STS Integrated Tomcat server. The file should be made to contain the following:

  <role rolename="tomcat" />
  <role rolename="manager" />
  <role rolename="admin" />
  <user username="admin" password="" roles="tomcat,manager,admin"/>

This will establish the "admin" user as available as a Tomcat Manager for the STS Integrated Tomcat server. Stop and start the STS Integrated Tomcat server to have the changes pick up.

You should now have access to the STS Integrated Tomcat Server manager:


You can now deploy your web application to the integrated Tomcat server using the following command:

mvn tomcat:deploy

And you can undeploy by using the following command:

mvn tomcat:undeploy

7.5. Subversion Policies

You should not commit any IDE or Maven-generated files to Subversion. In practical terms this means whenever you create a new directory that contains pom.xml, set the svn:ignore property as follows:

svn propset svn:ignore ".*
  target" directory_name_to_set

You will also want to remove any generated Eclipse or build products prior to commit:

mvn clean eclipse:clean

7.6. Site Deployment

Spring Surf includes Maven reports and documentation that can be generated for any particular release by running the following command:

mvn -Psite site

This will generate a site and all of the site's assets for the given release. This includes HTML and PDF documentation, tutorials and reports for the release.

If you wish to generate a site, you should do so using Maven 2.2.1. There is a bug in the Maven Site Plugin 2.0.1 which causes some of the generated links to be broken on Unix machines. The issue was resolved in Maven Site Plugin 2.1 which requires Maven 2.2.1.

For Spring surf site generation, all you have to do is run the above command using Maven 2.2.1. The command will activate a profile which uses Maven Site Plugin 2.1.

7.7. Releasing

Spring Surf is released on a regular basis by the Spring Surf project team. To build a release, ensure you perform an "svn update" first and then run "svnversion" to verify a standard Subversion revision number is given.

The following command can be used to build a release:

mvn clean install site assembly:assembly

This will create the build products in the "target" directory.

In addition, a SVN branch should be created using the copy command:

copy \ \
    -m "Tagging the 1.0.0.GA release"

7.8. Help

The following pages are available for Spring Surf. Whether you are a community user or a project developer, the following links will be of use:

7.9. How You Can Help

Helping people on the forum, presenting at JUGs/conferences, translation of resource bundles, third-party add-ons, documentation improvements, letting us know how you're using Spring Surf etc...