Chapter 1. Introduction

1.1. What are Spring Surf Developer Tools?

Spring Surf Developer Tools are easy-to-use productivity tools for rapidly building Spring Surf applications in the Script/Java programming languages and XML configuration files. It allows you to build high-quality and high-performance enterprise web applications in just minutes. Best of all, Spring Surf Developer Tools works alongside your existing Scripting/Java/XML knowledge , skills and experience. You probably won't need to learn anything new to use Spring Surf Developer Tools, as there's no new language or runtime platform needed. You simply program in your normal Scripting/Java way and Spring Surf Developer Tools just work.

1.2. Installation

Spring Surf Developer Tools consist of two components, a standard Spring Roo addon and an Eclipse plugin for providing a Surf based Spring Template Project. Both components are fully self-contained within the Spring Surf Developer Tools distribution ZIPs/JARs. You can download Spring Surf Developer Tools from one of the download sites , or build distribution ZIPs/JARs yourself from our source control repository.

If you are upgrading from an existing version of Spring Surf Developer Tools, you should consult the upgrade notes for important information.

Before attempting to install Spring Surf Developer Tools, please ensure you have the following system dependencies:

  • A Linux, Apple or Windows-based operating system.

  • A Sun, JRocket or IBM Java 5 or Java 6 installation, with the $JAVA_HOME environment variable pointing to the installation.

  • Apache Maven 2.0.10 or above installed and in the path for use with Roo-created projects.

  • SpringSource Tool Suite (STS), which is Spring's free Eclipse-based IDE that provides a fantastic workspace for building Spring applications. You can of course only install Spring Roo (part of SpringSource Tool Suite) if you are only interested in using Spring Surf Roo addon.

We always recommend you use the latest version of Java (Java 6) and Maven (2.2.x) that are available for your platform. It is required to use Maven 2.2.x for generating Surf site documentation.

It is also highly recommended to set up MAVEN_OPTS with suitable parameters. e.g.

MAVEN_OPTS='-Xmx1024m -XX:MaxPermSize=512m'

Once you have satisfied the initial requirements, you can install Surf Developer Tools by following these steps:

  1. Install SpringSource Tool Suite to a directory of your choice which will be known as $STS_HOME in the directions below. You can locate the Spring Roo home directory (e.g. roo-1.0.2.RELEASE) right under the $STS_HOME. This will be known as $ROO_HOME.

    If you prefer only install Spring roo seperately, you can unzip the Roo installation ZIP to a directory of your choice which will be known as $ROO_HOME in the directions below as well.

  2. If using Windows, add $ROO_HOME\bin to your %PATH% environment variable

  3. If using Linux or Apple, create a symbolic link using a command such as sudo ln -s $ROO_HOME/bin/ /usr/bin/roo

  4. Surf provides an addon for Spring Roo which allows you to quickly scaffold Surf pages and views on top of your Spring MVC application.

    To install the Surf addon for Spring Roo, you need to start Spring Roo shell and run the following roo command.

    addon install --url
    roo> addon install --url
    Received 355781 bytes
    Written to D:\Alfresco\dev\spring-roo\spring-roo-1.0.2.RELEASE\add-ons\
    Performing clean
    Roo home.....: D:\Alfresco\dev\spring-roo\spring-roo-1.0.2.RELEASE
    Add-ons dir..: D:\Alfresco\dev\spring-roo\spring-roo-1.0.2.RELEASE\add-ons
    Work dir.....: D:\Alfresco\dev\spring-roo\spring-roo-1.0.2.RELEASE\work
    SAVED spring-surf-roo-addon-1.0.0-RC2.jar

    Once it finishes, you should be able to use "addon list" command to view the updated addon list or "addon remove" command to uninstall the Surf addon if necessary.

  5. Surf also provides a Spring template project which allows you to quickly scaffold Surf pages and views within Spring Tool Suites.

    To install the Surf Spring template project, all you need to do is to install latest release of Spring Surf Dev tools in Eclipse. You can use the following update sites to directly install the devtools:

    Note: the dev tool installation will require installation of Jboos FreeMarker editor

Next verify Spring Surf Developer Tools have been installed correctly.

For the Surf Roo addon, it can be done using the following commands:

$ mkdir surf-test
$ cd surf-test
$ roo
    ____  ____  ____
   / __ \/ __ \/ __ \
  / /_/ / / / / / / /
 / _, _/ /_/ / /_/ /
/_/ |_|\____/\____/    W.X.Y.ZZ [rev RRR]

Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER.
$ roo> project --topLevelPackage surf.test
Created D:\Alfresco\dev\spring-roo\sandbox\surf-test\pom.xml
Created SRC_MAIN_RESOURCES\META-INF\spring\applicationContext.xml
roo> help surf install
Keyword:                   surf install
Description:               Installs Surf artifacts into your project.
 Keyword:                  siteName
   Help:                   Specifies site name for your Surf project (last segment 
   of package name used as default).
   Mandatory:              false
   Default if specified:   '__NULL__'
   Default if unspecified: '__NULL__'

Keyword:                   surf install
Description:               Installs Surf artifacts into your project.
 Keyword:                  siteName
   Help:                   Specifies site name for your Surf project (last segme
nt of package name used as default).
   Mandatory:              false
   Default if specified:   '__NULL__'
   Default if unspecified: '__NULL__'

* surf install - Installs Surf artifacts into your project.

** Type 'hint' (without the quotes) and hit ENTER for step-by-step guidance **			
$ roo> exit
$ roo> cd ..
$ rmdir surf-test

If you see the help message for Roo surf install command, you've installed and configured Surf Roo addon successfully.

For the Surf Spring template project, let us first start Spring Tool Suite by running the STS executable. We would recommend to start STS in clean mode if you start it for the first time right after Surf Spring Developer tools installation. It will flushe the registry caches (among other information), force the plug-in manifests to be parsed in order to regenerate the registry and definitely save you a lot of time and headaches.

sts.exe -clean

If things are all set, you should see the SpringSource splash screen come up.

From the STS menu, select File -> New -> Spring Template Project

In the New Template Project window, locate and click the Refresh button. In the updated project template list, you should see the option for Spring Surf project which indicates that you have installed and configured Surf Spring template project successfully.

1.3. First Steps: Your Own Spring Surf App in Under 5 Minutes

Now that you have installed Surf Developer Tools, let's spend a couple of minutes building an enterprise application using Surf Developer Tools.

The purpose of this application is just to try out Surf Developer Tools. We won't explain what's going on in these steps, but don't worry - we'll do that in the next chaper, Beginning With Surf Developer Tools: The Tutorial. We will try to teach you about some usability features as we go along, though.

Please start by typing the following commands:

$ mkdir surf-app
$ cd surf-app
$ roo
    ____  ____  ____
   / __ \/ __ \/ __ \
  / /_/ / / / / / / /
 / _, _/ /_/ / /_/ /
/_/ |_|\____/\____/    W.X.Y.ZZ [rev RRR]

Welcome to Spring Roo. For assistance press TAB or type "hint" then hit

Let's first setup a basic Spring project which allows us to use other features that Spring Roo provides:

roo> project --topLevelPackage
Created /Users/drq/dev/spring/roo/sandbox/surf-app/pom.xml
Created SRC_MAIN_RESOURCES/META-INF/spring/applicationContext.xml

At this point you've now got a viable Maven-based project setup and you are ready to install Surf related artifacts.

roo> surf install
Created SRC_MAIN_WEBAPP/WEB-INF/config/surf-config.xml
Created SRC_MAIN_WEBAPP/WEB-INF/config/surf-interop-config.xml
Created SRC_MAIN_WEBAPP/WEB-INF/config/web-application-config.xml
Managed ROOT/pom.xml
Created SRC_MAIN_WEBAPP/WEB-INF/urlrewrite.xml
Created SRC_MAIN_WEBAPP/WEB-INF/surf.xml
Managed ROOT/pom.xml
Created SRC_MAIN_WEBAPP/css/sample.css
Created SRC_MAIN_WEBAPP/images
Created SRC_MAIN_WEBAPP/images/alfresco3d.jpg
Created SRC_MAIN_WEBAPP/images/AlfrescoLogo200.jpg
Created SRC_MAIN_WEBAPP/images/AlfrescoLogo32.jpg
Created SRC_MAIN_WEBAPP/images/background1.gif
Created SRC_MAIN_WEBAPP/images/bg.gif
Created SRC_MAIN_WEBAPP/images/chrome/box
Created SRC_MAIN_WEBAPP/images/chrome/box/box_chrome_header_bg.gif
Created SRC_MAIN_WEBAPP/images/cmis32.jpg
Created SRC_MAIN_WEBAPP/images/cmis_logo_100.jpg
Created SRC_MAIN_WEBAPP/images/gifts-and-gadgets.jpg
Created SRC_MAIN_WEBAPP/images/our-services.jpg
Created SRC_MAIN_WEBAPP/images/powered-by-spring.jpg
Created SRC_MAIN_WEBAPP/images/PoweredBySurf.jpg
Created SRC_MAIN_WEBAPP/images/products-overview.jpg
Created SRC_MAIN_WEBAPP/images/surf32.jpg
Created SRC_MAIN_WEBAPP/images/SurfLogo200.jpg
Created SRC_MAIN_WEBAPP/WEB-INF/chrome/box
Created SRC_MAIN_WEBAPP/WEB-INF/chrome/box/chrome.jsp
Created SRC_MAIN_WEBAPP/WEB-INF/chrome/titled
Created SRC_MAIN_WEBAPP/WEB-INF/chrome/titled/chrome.jsp
Created SRC_MAIN_WEBAPP/WEB-INF/classes/surf/site/chrome
Created SRC_MAIN_WEBAPP/WEB-INF/classes/surf/site/chrome/box.xml
Created SRC_MAIN_WEBAPP/WEB-INF/classes/surf/site/chrome/titled.xml
Managed SRC_MAIN_WEBAPP/WEB-INF/config/web-application-config.xml
Created SRC_MAIN_WEBAPP/WEB-INF/pages/calendar
Created SRC_MAIN_WEBAPP/WEB-INF/pages/calendar/calendar.xml
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home/home.xml
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home/main.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home/main.get.head.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home/main.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home/side.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/pages/home/side.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/pages/products
Created SRC_MAIN_WEBAPP/WEB-INF/pages/products/main.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/pages/products/main.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/pages/products/products.xml
Managed SRC_MAIN_WEBAPP/WEB-INF/surf.xml
Created SRC_MAIN_WEBAPP/WEB-INF/templates
Created SRC_MAIN_WEBAPP/WEB-INF/templates/home.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/templates/home.xml
Created SRC_MAIN_WEBAPP/WEB-INF/templates/landing.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/templates/landing.xml
Created SRC_MAIN_WEBAPP/WEB-INF/templates/sample
Created SRC_MAIN_WEBAPP/WEB-INF/templates/sample/login.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/templates/sample/logout.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/templates/sample/userinfo.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/calendar
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/calendar/calendar.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/calendar/calendar.get.head.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/calendar/calendar.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/footer
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/footer/footer.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/footer/footer.get.head.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/footer/footer.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/footer/footer.get.js
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/header
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/header/header.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/header/header.get.head.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/header/header.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/header/header.get.js
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/horizontal.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/horizontal.get.head.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/horizontal.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/horizontal.get.js
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/vertical.get.desc.xml
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/vertical.get.head.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/vertical.get.html.ftl
Created SRC_MAIN_WEBAPP/WEB-INF/webscripts/navigation/vertical.get.js
Created SRC_MAIN_WEBAPP/WEB-INF/classes/log4j.dtd
Created SRC_MAIN_WEBAPP/WEB-INF/classes/log4j.xml
Created SRC_MAIN_WEBAPP/WEB-INF/classes/surf/site/configurations
Created SRC_MAIN_WEBAPP/WEB-INF/classes/surf/site/configurations/

This command installs all required Surf configuration files into your project with the Surf Quick Start application that consists of a few Surf pages, templates, components etc. At this point, we should be able to test the Surf app right the way.

Since a Jetty 7 server plugin has been installed and configured within the generated pom.xml, it is highly recommended to use this Jetty server for future development and testing.

Now let us open a new terminal or command prompt and change the directory to the surf-app project.

Run following maven command to package Surf application, start the Jetty server and deploy the Surf Application:

mvn clean package jetty:run

Once the Jetty server is started, we are ready to visit our new Surf application at http://localhost:8180/.

Please note that the Jetty server uses port 8180. It is actively scanning src/main/webapp folder which means any changes we make to the Surf application will be automatically picked up by the Jetty server.

Since the webapp contex of the current project is set up as "/" (root), we won't have the webapp name in the URLs.

At this point, all other Surf commands will be available to you. Try typing "surf" and then using the TAB key, the Roo shell will display a list of Surf commands.

surf addon install
surf addon list
surf component create
surf component list
surf component property create
surf component resource create
surf content association create
surf page association create
surf page association list
surf page create
surf page list
surf report page
surf site create
surf template create
surf template instance create
surf template instance list
surf template list
surf template region list
surf webscript list

Naturally in this short five minute test we've skipped dozens of features that Surf Developer Tools can provide, and didn't go into any detail on how you could have customised the application. We just wanted to show you that it works and you can build an application in record-time. The Beginning With Surf Developer Tools: The Tutorial chapter will go through the process of building an application in much more depth, including how to work with your IDE and so on.

1.4. Exploring the Surf Roo Samples

Now that you've built your first application during the five minute test , you have a rough idea of how it works. To help you learn Surf Roo Commands we ship a sample script that can be used as samples for building your new applications. This sample script has been packaged into the Surf Roo addon jar. You can run any sample script by using the follow command:

roo> script surfquickstart.roo

1.5. Suggested Steps to Surf Productivity

As we draw to the close of this first chapter, you know what Surf Developer Tools are, why you'd like to use it, have installed it and completed the five minute test, plus you know which samples are available. You could probably stop at this point and apply Surf Developer Tools productively to your projects, but we recommend that you spend a couple of hours learning more about Surf Developer Tools. It will be time well spent and easily recouped by the substantially greater productivity Roo will soon deliver on your projects.

The next step is to complete the Beginning With Roo: The Tutorial chapter. In the tutorial chapter you'll learn how to use Surf Developer Tools with your preferred IDE and how flexible and natural is to develop with Surf Developer Tools. After that you should read the application architecture chapter to understand what Surf applications look like. From there you might wish to wrap up the recommended tour of Surf Developer Tools with a skim over the usage and conventions chapter. This final recommended chapter will focus more on using the Roo tool and less on the applications that Roo creates.

If you can't find the information you're looking for in this reference guide, the resources chapter contains numerous Surf-related web sites and other community resources.

We welcome your comments and suggestions as you go about using Surf. One convenient way to share your experiences is to Tweet with the #springsurf hash code. In any event, we thank you for exploring Surf Developer Tools and hope that you enjoy your Surf journey.