SANDev readme:
intro
Welcome to the SANDev readme. This file explains how to install and get
started. For general info on Structs and Nodes Development (SAND), please
see sandev.org. If you are reading this
online, you can download the latest SANDev release from
sourceforge. Unzip
to your local drive.
configuration
SANDev generates framework code from your struct and node declarations,
then combines this with your deployment configuration and UI definition to
create a .war file for your app. To do this, SANDev needs to know where to
find and put things, which is declared in the
"general environment settings" section of the
apps/basics/build/mainbuild.xml
include file. The properties SANDev needs are:
| property |
default value |
description |
| SAND_HOME |
${runenv.SAND_HOME} |
The root directory for SAND. For example c:\sand |
| SAND_DEPLOY |
${runenv.TOMCAT_HOME}/webapps |
Where the resulting application .war should be placed. |
| JAVA_LIB |
${runenv.JAVA_HOME}/lib |
Where doclet support tools.jar can be found. |
| J2EE_LIB |
${runenv.J2EE_HOME}/lib |
Where the servlet, mail, and JMS declarations can be found. JMS
is not required at runtime unless it is used.
|
| JMX_LIB |
${runenv.TOMCAT_HOME}/bin |
Where the JMX management classes can be found.
|
| WEBAPP_EXE |
${runenv.WEBAPP_EXE} |
The runtime directory for the webapp. For example C:\WINDOWS\system32
|
Apache Ant
The SANDev build is based on Apache
Ant, which you will need to download and install if you haven't already
got it. The extensions are in sandbuild.jar which needs to be
in your CLASSPATH (along with ant.jar). Here's an example
CLASSPATH from a windoze development box:
CLASSPATH=c:\apache-ant-1.6.2\lib\ant.jar;c:\sand\platform\sandbuild\env\sandbuild.jar
If you want to recompile sandbuild.jar for any reason:
>cd %SAND_HOME%\platform\sandbuild\build
>ant clean
>ant
(Or the equivalent for *nix)
Servlet container
The output of a SANDev build is a .war file which is deployed to the
local servlet container. The local servlet container is also used for the
config and UI editor tools. Any servlet container will probably work, but
we recommend
Apache Tomcat.
After installing, set the TOMCAT_HOME environment variable. For example
on a windoze dev box
TOMCAT_HOME=C:\Program Files\Apache Software Foundation\Tomcat 5.0
SANDev requires outbound mail support at runtime. To add support for
this to Tomcat, I downloaded javamail-1_3_2.zip from
java.sun.com/products/javamail,
unzipped it, and copied mail.jar and activation.jar
into TOMCAT_HOME/common/lib.
Database Management System (DBMS)
SANDev requires a DBMS. Any software supporting a JDBC driver should
work. In the past we have used
HSQL and
MySQL. Our current recommendation is
to use PostgreSQL. After installing,
download the appropriate JDBC driver from
jdbc.postgresql.org into
TOMCAT_HOME/common/lib.
Create database
To run the SANDev demonstration application (TaskHeapDemo),
you will need to create a database for it to use, and describe that database
in the default <sandpersist> declaration of the
deploy/TaskHeapDemo/build/build.xml
file. There are two <sandpersist> declarations: one for
release the release build (requiredMode="release") and one for local
development build (requiredMode="default"). In the default sandpersist
declaration, edit the last three parameters of the
dataSource field describing the database name, username,
and password to match the database you have created. By default the
database name is "taskheap", the database username is "postgres", and the
database password is "development".
If you are using a database other than PostgreSQL, you will want to
change the JDBC driver name, and the structMapperClass to
HSQLDBStructMapper, MySQLStructMapper, or DefaultSQLStructMapper. You
can also create your own StructMapper if you want to change how data is
mapped to the database you are using. See the source files in
SAND_HOME/apps/basics/build/generate/org/sandev/generator
for details.
Build TaskHeapDemo
After the database is set up, build the demo:
>cd sand/deploy/TaskHeapDemo/build
>ant
The SANDev build process has the following stages:
- Load: The current project and any of the projects it requires
are loaded and organized in dependency order.
- Code generation: The code generators are run according to their
scope (local project, cross project, struct, node, or both).
- Standard build: Compile, .jar, .war, javadoc for each project.
- Deployment: .war repackaging and copying to local deployment.
The build process checks dependencies as best it can to make incremental
development builds as fast as possible. Use ant scrub to
clear everything and rebuild from scratch.
Run TaskHeapDemo
Building TaskHeapDemo (or any deployment project), creates
a static website encompassing all included projects and documentation. The
root page of the generated docsite is
docs/index.html which provides links to
supporting tools and additional docs (including the
SANDev directory structure and
build process). Clicking the
TaskHeapDemo link in the project tree in the upper left brings
you to the TaskHeapDemo doc page, which has a link to the locally deployed
TaskHeapDemo application. Normally the demo application is accessible as
localhost:8080/THD_TaskHeapDemo/TaskHeap.
If everything deployed properly, you should be prompted with a login
screen. Login as admin/whatever if you want to try out the
TaskHeap application. Click the help link after logging in to
access the user manual.
Create your projects
A typical SAND project consists of an application and a deployment.
So for a project called MyApp you would create:
sand/apps/MyApp
sand/deploy/MyAppMain
each with the following subdirectories and files:
build
docs
intro.html (contains a description of the project)
src (contains the struct and node definitions)
Create your structs
A struct is a plain java class declaration with a name ending in
"Struct" which is placed into the structs source directory. So the
source file would be something like:
sand/apps/MyApp/src/org/MYDOMAIN/MyApp/structs/MyDataStruct.java
For some working struct declarations see:
TaskStruct.java or
PlanComponentStruct.java
A struct contains only protected data member variables and meta tags.
The base types for data members can be:
int, long, double, String, Date
- a reference to a persistent struct (
long with reference
metatag)
- another struct type (except persistent structs which may not aggregate)
- arrays of any of the above
Types can be further refined in generated code using metadata tags. At the
class level, a struct declares itself using
By convention the struct level tags are named StructTag*. Use
the FieldTag* tags for member data variable declarations. See
org.sandev.generator.tags
for a complete list of metadata tag descriptions.
A struct may extend another struct.
Create your nodes
A node is a plain java class declaration with a name ending in "NodeDecl"
which is placed into its own source package. So the source file would be
something like:
sand/apps/MyApp/src/org/MYDOMAIN/MyApp/MyLogic/MyLogicNodeDecl.java
For some working node declarations see:
PlanCalculatorNodeDecl.java or
TaskHeapUINodeDecl.java
A node may declare configuration parameters using the primitive types
int, long, double, String, Date
and the associated subset of struct metadata. A node declares all of its
communication requirements and supported processing through:
tags. The tags are translated into supporting code in the generated
NodeBase source file and used by the business logic in the
hand coded Node file. For MyLogicNode, the
source file structure is:
public class MyLogicNodeDecl
public class MyLogicNodeBase extends MyLogicNodeDecl //generated file
public class MyLogicNode extends MyLogicNodeBase
Create your config
The bootstrap data for your application, the server(s) it runs on, and
the nodes that make up the runtime architecture are declared using the
Configuration Editor which is accessed via a link off
the deployment project docsite page. The configuration is saved in the
config.xml file in the env directory of the
deployment. For an example see
deploy/TaskHeapDemo/env/config.xml.
Until the graphical configuration editor is completed, we recommend
placing a drawing of your configuration into the intro.html file for your
deployment to serve as a reference. For details on the configuration
structure, see the description of the struct in the basics
project. Also see Messaging.html in
the top level docs.
Create your UI
The screens that make up your application, the forms, custom tabs,
custom action buttons, and generated output values are declared using the
SandUI Editor which is accessed via a link off the
deployment project docsite page. The UI definition is saved in the
SandUI.xml file in the env directory of the
deployment and becomes part of your deployment .war file. For an example
see
deploy/TaskHeapDemo/env/TaskHeapDemoSandUI.xml.
For details on the SandUI structure, see the description of the struct
in the ui project. Also see
UIGen.html in the top level docs.
Customize your display
With the SandUI and supporting code defined, the default templates
provide enough functionality to enter development data, which completes the
raw material for creating a custom UI display. To customize, edit the XSLT
templates are stored in the webapp/templates subdirectory of
the deployment. Rebuild to redeploy the changes.
During the early stages of UI development, it is sometimes helpful to
retrieve the raw XHTML output from your application, save it to a file, and
then work applying your template to that file directly rather than
rebuilding and redeploying the app for each minor change. To retrieve the
unconverted XHTML output from your app, specify the raw=true
URL parameter. The base UIActionHandler also allows you to specify the
screen, message class, uniqueID and action button name. Some examples:
http://localhost:8080/THD_TaskHeapDemo/TaskHeap?scr=Main&class=Resource&id=1202
http://localhost:8080/THD_TaskHeapDemo/TaskHeap?scr=Main&class=Resource&id=1202&button=edit
http://localhost:8080/THD_TaskHeapDemo/TaskHeap?scr=Main&class=Resource&id=1202&raw=true
See the templates in the TaskHeapDemo webapp directory for other useful
techniques.
|