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 and Maven that are available for your platform. It is required to use Maven 2.2.1 for generating Surf documentation.

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.0.RC4) 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/roo.sh /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 download the latest milestone release of Surf addon zip file spring-surf-roo-addon-1.0.0.M2-roo-addon.zip or the lastest snapshot spring-surf-roo-addon-1.0.0.CI-SNAPSHOT-roo-addon.zip.

    And then start Spring Roo shell and run the "addon install" command.

    You should replace the file path in the following command with your own.

    roo> addon install --url file:/Alfresco/dev/spring/svn/trunk/spring-surf-devtools/spring-surf-roo-addon/target/spring-surf-roo-addon-1.0.0.M2-roo-addon.zip
    Downloading file:/Alfresco/dev/spring/svn/trunk/spring-surf-devtools/spring-surf-roo-addon/target/spring-surf-roo-addon-1.0.0.M2-roo-addon.zip
    Received 355781 bytes
    Written to D:\Alfresco\dev\spring-roo\spring-roo-1.0.0.RELEASE\add-ons\spring-surf-roo-addon-1.0.0.M2-roo-addon.zip
    Performing clean
    
    Roo home.....: D:\Alfresco\dev\spring-roo\spring-roo-1.0.0.RELEASE
    Add-ons dir..: D:\Alfresco\dev\spring-roo\spring-roo-1.0.0.RELEASE\add-ons
    Work dir.....: D:\Alfresco\dev\spring-roo\spring-roo-1.0.0.RELEASE\work
    
    >>>>> spring-surf-roo-addon-1.0.0.M2-roo-addon.zip
    SAVED spring-surf-roo-addon-1.0.0.M2.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 download the latest milestone release of Surf Eclipse plugin spring-surf-sts-addon_1.0.0.M2.jar or the latest snapshot spring-surf-sts-addon_1.0.0.CI-SNAPSHOT.jar.

    You should copy the file into the following path: $STS_HOME/sts-2.3.0.RELEASE/plugins.

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_JAVA
Created SRC_MAIN_RESOURCES
Created SRC_TEST_JAVA
Created SRC_TEST_RESOURCES
Created SRC_MAIN_WEBAPP
Created SRC_MAIN_RESOURCES\META-INF\spring
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 recommand you 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
ENTER.

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

roo> project --topLevelPackage org.app.surf
Created D:\Alfresco\dev\spring-roo\sandbox\surf-app\pom.xml
Created SRC_MAIN_JAVA
Created SRC_MAIN_RESOURCES
Created SRC_TEST_JAVA
Created SRC_TEST_RESOURCES
Created SRC_MAIN_WEBAPP
Created SRC_MAIN_RESOURCES\META-INF\spring
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
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
Created SRC_MAIN_WEBAPP\WEB-INF\web.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\surf-sample-site.zip
Created SRC_MAIN_WEBAPP\css
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\images\Thumbs.db
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\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
Deleted SRC_MAIN_WEBAPP\surf-sample-site.zip
Created SRC_MAIN_WEBAPP\WEB-INF\classes\surf\site\configurations
Created SRC_MAIN_WEBAPP\WEB-INF\classes\surf\site\configurations\default.site.configuration.xml

This command installs all required Surf configuration files into your project. It also adds the Surf Quick Start app which consists of a few Surf pages, templates, components etc. It will help to test the Surf app right the way.

Now let us exit Roo shell and test the application using a local tomcat server.

Before we start the testing, let us first install a local tomcat server. You can find the tomcat 6 download link from Apache Web Site. Once we download and unzip the bundle for tomcat 6 server, we need to add following configurations to conf/tomcat-users.xml

<tomcat-users>
...
<role rolename="manager"/>
<user username="admin" password="" roles="manager"/>
...
</tomcat-users>

We can then start up the local tomcat server and are ready to run following maven command to deploy the Surf Application war:

mvn tomcat:deploy

Once the war file is deployed, we are ready to visit our new Surf application at http://localhost:8080/surf.

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