One Page Manual

Installation

Download and install Java SE 5 or greater from Sun's Java Site.
Install Apache Maven 2.x and verify Maven's installtion per Maven document
Install latest Apache Ant (Optional, if you want to use ANT task instead of Spring-On-Rails' Maven plugin)
Download and extract latest Spring-On-Rails source distribution
Change directory to newly created Spring-On-Rails directory from above step.
Build and Install Spring-On-Rails.

     mvn clean install

A BUILD SUCCESSFUL message should display at the end of installation like below

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] spring-on-rails ....................................... SUCCESS [1.703s]
[INFO] spring-on-rails-core .................................. SUCCESS [4.688s]
[INFO] maven-springonrails-plugin ............................ SUCCESS [1.656s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 8 seconds
[INFO] Finished at: Sun Oct 07 20:05:58 EDT 2007
[INFO] Final Memory: 13M/24M
[INFO] ------------------------------------------------------------------------

Installation is complete now.
Run the following command to generated DEMO application;

ant

Change directory to demo project directory (default is "Sunny_DEMO");
Run the following command to try out newly generated application

   mvn jetty:run

launch your web browser to http://localhost:8080/<Sunny_DEMO>/index.jsp
Examine generated source file in ./target/src/main directory

Getting started in 5 minutes

Create entity mapping xml file

copy and past the following example, save it as "mytypemap.xml" somewhere in your computer.

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.asksunny.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.asksunny.com typeMap.xsd">	
	<entity javaName="Employee" tableName="Employee">
		<property javaName="ssn" columnName="ssn" allowNull="false"
		primaryKey="true" javaType="string" sqlType="CHAR(11)"/> 
		<property javaName="firstName" columnName="First_Name" allowNull="false"
		javaType="String" sqlType="VARCHAR2" length="64"/>	
		<property javaName="lastName" columnName="Last_Name" allowNull="false"
		javaType="String" sqlType="VARCHAR2" length="64"/>			
	</entity>		 
</map>

Modify ANT build file
In Spring-On-Rails <Installation_Folder>, open up build.xml and copy the following example and past it on build.xml, change target name to "myFirstRails" without quote. Modify springOnRailsTask's attribute accordingly.

<target name="onRailsTarget">
	    <taskdef name="springOnRailsTask" 
	    	classname="com.asksunny.springonrails.ant.SpringOnRailsTask">	
	    	<classpath refid="SpringOnRails_lib"></classpath>
	    </taskdef>		
		<springOnRailsTask  
	    	entityMappingLocation = "File_PATH_TO_mytypemap.xml" 
	    	outputPackageName = "your.java.output.package.name.prefix"  
	    	outputDir = "FILE_PATH_WHERE_YOU_WANT_SOURCE_FILE_TO_BE"
	    	projectName= "PICK_YOUR_FAVORITE_PROJECT_NAME_IN_SHORT"
	    	/>	   

</target>

Run ANT build
It is time to see Spring-On-Rails in action now. Change directory to Spring-On-Rails <Installation_Folder> from unix shell/window command shell and run the following command:

UNIX:

$ant myFirstRails

Windows:

>ant.bat myFirstRails

Use Spring-On-Rails Maven plugin instead of ANT task

This is new addition to Spring-On-Rails for who does not like mixture of ANT in Spring-On-Rails. Orignally planned Maven archetype seems taking more steps to get job done, I decided to use Maven plugin only.

copy the following xml and save as pom.xml where you want to run Spring-On-Rails Maven plugin.

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>I.want.to.fool.maven</groupId>
  <artifactId>Dummy</artifactId>
  <packaging>war</packaging>
  <version>1.0</version>
  <name>A custom project</name>
  <url>http://www.springonrails.org</url>  
</project>

Run the follwing command where above pom.xml is located.

mvn springonrails:rails  \
-DentityMappingLocation=<ENTITY_MAPPING_FILE> \
-DoutputDirectory=<PATH_TO_OUTPUT_DIRECTORY> \
-DgroupId=<OUTPUT_PACKAGE_NAME> \
-DartifactId=<PROJECT_NAME>

Start up Jetty Web Server
Change directory to your output directory that you specified at step 2. Change directory of your project name (step 2). And run following command.
mvn jetty:run

Please wait until Jetty fully started and proceed to next step.

Try out newly created application with your favirite browser
enter http://localhost:8080/<Your_Project_Name>/index.jsp to your browser's address bar. your should be able to see your newly created Java Enterprise Application in a couple seconds.

Now it is time to see what have been generated.

Spring-On-Rails' application file Structure

Now, it is time to examine source files that were generated by Spring-On-Rails. There isn't any surprise here. Directory structure is pretty much standard Maven's file structure as shown at below.

<Project_Name>
    |----pom.xml
    |----src
         |----main
               |----webapp
               |     |----WEB-INF
               |     |      |----dataAccess1Context.xml
               |     |      |----dataAccess2Context.xml
               |     |      |----jdbc.properties
               |     |      |----log4j.properties
               |     |      |----spring1-servlet.xml
               |     |      |----spring2-servlet.xml
               |     |      |----sql-map-config.xml
               |     |      |----web.xml
               |     |      |----JSP
               |     |            |--<XXX>.jsp
               |     |----src
               |           |--main
               |               |--resources
               |                   |--entity.ddl
               |----java
                     |--<package-prefix>
                           |--controller
                           |    |--Spring<XXX>Controller.java
                           |--dao
                           |   |--<XXX>DAO.java
                           |   |--ibatis
                           |   |    |--<XXX>DAOImpl.java
                           |   |--mock
                           |       |--<XXX>DAOImpl.java
                           |   |--hibernate
                           |       |--<XXX>DAOImpl.java
                           |--model
                           |   |--mapping
                           |   |    |--<XXX>.xml
                           |   |--<XXX>.java
                           |--trans
                           |   |--TransactionProxy.java
                           |   |--TransactionProxyImpl.java
                           |--web
                           |   |--view
                           |       |--FlexXMLView.java
                           |       |--FlexXMLViewResolver.java
                           |--xml
                               |--AbstractObjectXMLSerializer.java
                               |--DefaultObjectXMLSerializer.java
                               |--ErrorXMLSerializer.java
                               |--ObjectXMLSerializer.java
                               |--ObjectXMLSerializerFactory.java
                               |--SimpleBeanXMLSerializer.java

IDE Integration

Change directory to your project's root directory.

Eclipse

Run following command first

mvn eclipse:eclipse

Start up eclipse and import existing project into eclipse

Netbeans

mvn netbeans-freeform:generate-netbeans-project

IntelliJ

mvn idea:idea

At this point, I assume you know how to proceed to next step.

Anatomy of Entity Mapping File

example of entity mapping file:

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.asksunny.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.asksunny.com typeMap.xsd">
<meta><![CDATA[
	controllerType=multiple	
	ormType=hibernate
	springVersion=2	
	jeeVersion=4
]]></meta>		

<entity javaName="BudgetServer" tableName="BUDGET_SERVER" viewLabel="Budget Server">
		<property javaName="serverId" columnName="server_id" allowNull="false"
		primaryKey="true" 
		javaType="int" sqlType="NUMBER(10)" /> 
		<property javaName="serverName" columnName="server_name" 
		javaType="String" sqlType="VARCHAR2" length="32"> 
			<set><![CDATA[
				if(serverName==null || serverName.length()>32) throw new IllegalArgumentException("invalid serverName " + serverName);		
				this.serverName = serverName;
			]]></set>
		</property>
		<property javaName="price" columnName="price" 
		javaType="double" sqlType="NUMBER(16, 2)" /> 
		<methods><![CDATA[
		//Addition methods to add to PoJo class.
                public void doSomething()
		{
			//We have nothing to do here;
		}		
		
		public String returnAfterMessage()
		{			
			return serverId + " >>" + serverName;			
		}		
		]]></methods>
	</entity>	
</map>

explanation of entity mapping file:

1. <meta> element

<meta> element is used to instruct Spring-On-Rails to generate application accorddingly. It uses Java Properties format. This element is optional, many of them can also be specified in ANT build file. However, properties in this section will override those specified in ANT build file. The following are available properties and its coresponse value.

Property Name	Property Value	Explanation
jeeVersion	3 or 1.3	J2EE Version 1.3
	4 or 1.4	J2EE Version 1.4
	5 or 1.5	J2EE Version 1.5
controllerType	single	one Spring MVC controller for each entity. Create, read, update, and delete functions will be on same controller.
	multiple	one Spring MVC controller for each action, each entity has four controllers
springVersion	1	Using Spring 1.2.x
	2	Using Spring 2.x.x
ormType	hibernate	Uses hibernate as ORM for generated application, it also generates Hibernate mapping file for each entity and setups Hibernate configuration in Spring DataAccessContext.xml file
	ibatis	Uses Ibatis as ORM for generated application, it also generates Ibatis mapping file for each entity and setups Ibatis configuration in Spring DataAccessContext.xml file
dbType	oracle	Uses Oracle 9i or above as backend storage
	mssql	Uses SQL server 2000 or 2005 above as backend storage
	mysql	Uses MySQL 5.x or above as backend storage
	sybase	Uses Sybase 12.5 or above as backend storage
	db2	Uses DB2 7 or above as backend storage
viewType	jstl	Using Java Standard Tag Library
	xml	output xml
	both	default JSTL, but add ?view=xml to URL, it will display xml out also
	ws or webservice	XFire Web Service
	springView	Using Spring form bean (not implemented yet)

2. <entity> element

<entity> element represents a Java type and database table definition.