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.
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:
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.
If using Windows, add
$ROO_HOME\bin
to your
%PATH%
environment variable
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
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 http://www.springsurf.org/downloads/1.0.0-RC2/spring-surf-roo-addon-1.0.0-RC2-roo-addon.zip
roo> addon install --url http://www.springsurf.org/downloads/1.0.0-RC2/spring-surf-roo-addon-1.0.0-RC2-roo-addon.zip Downloading http://www.springsurf.org/downloads/1.0.0-RC2/spring-surf-roo-addon-1.0.0-RC2-roo-addon.zip Received 355781 bytes Written to D:\Alfresco\dev\spring-roo\spring-roo-1.0.2.RELEASE\add-ons\spring-surf-roo-addon-1.0.0-RC2-roo-addon.zip 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 >>>>> spring-surf-roo-addon-1.0.0-RC2-roo-addon.zip 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.
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_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
Created SRC_MAIN_RESOURCES\META-INF\spring\log4j.properties
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-testIf 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.
 |
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 /Users/drq/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 Created SRC_MAIN_RESOURCES/META-INF/spring/log4j.properties
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 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/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/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 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 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.
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
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.