Structs and Nodes Development (SAND)

How to use it:

Verify you have Java, Tomcat, PostgreSQL (or MySQL or equivalent), Ant, and preferably CVS installed.
Download SAND.
Build the sample project to test everything is working and get a feel for SAND.
Create your own project.

Prerequisite software:

SAND is built on Java. Although it could theoretically be applied to any language that supports comments, being OO with support for interfaces doesn't hurt, and Java is all that has been done so far. SAND could also be applied to a variety of deployment environments, but currently it targets a web server/relational database environment. SAND requires a two stage build: first the generators update any generated code that needs to be changed, then the standard compilation and packaging. The build is currently implemented using Ant with some custom tasks. To use SAND you will need this prerequisite software.

Java

Download and install the JDK (aka J2SE at the time of this writing). After installing, define the JAVA_HOME environment variable to be the location where Java was installed. The SAND build looks for JAVA_HOME/lib for the .jar files to compile with.

Compatibility notes:

If you are using 1.5 or later you may notice "uses unchecked or unsafe operations" compiler messages since our code uses the old school "untyped" collections.
If you are using 1.4 or earlier, you will need to define a couple of stub classes for symbol resolution when compiling the generators. In SAND_HOME/apps/basics/build/generate/org/sandev/generator create empty class declarations in the com.sun.javadoc package:
1. AnnotationDesc.java
2. AnnotationTypeDoc.java
3. ParameterizedType.java
4. TypeVariable.java
5. WildcardType.java

Tomcat

Download and install Tomcat. After installing, define the TOMCAT_HOME environment variable to be the directory where tomcat was installed (e.g. one level up from where the "webapps" directory is).

Turbocharge your installation with the following additional capabilities that SAND needs:

Mail: Download javamail together with the required JavaBeans Activation Framework. Copy mail.jar and activation.jar into tomcat lib.
JMS: If you are using JMS messaging, then add the JMS support files from your vendor into tomcat/lib. Otherwise you can download the JMS API and copy the .jar files into tomcat lib for SAND to use for compilation. JMS is not required at runtime unless you specify using the AuthorizedJMSMessager for your deployment.

Define the J2EE_HOME environment variable to be the location of these additional tomcat files. The build will look in J2EE_HOME/lib for the .jar files it needs.

PostgreSQL (or MySQL or equivalent)

By default, SAND uses JDBC for persistence. If you do not already have a JDBC database installed, download PostgreSQL and install it. Then copy the runtime driver into the tomcat lib area where you put the mail and messaging support jar files.

Using other databases:

To use a different JDBC database, you will need to change sandpersist declarations in the build.xml for the deployment (so if you were building TaskHeapDemo, you would edit sand/deploy/TaskHeapDemo/build.xml). Locate the lines that look like
and
Change the structMapperClass to specify the appropriate class. For example org.sandev.generator.MySQLStructMapper, org.sandev.generator.DefaultSQLStructMapper, or your own custom mapping specification. Change the datasource to be whatever your database documentation specifies should be used for a JDBC connection.
To use a non-JDBC database, you will need to change the persisterClass for the sandpersist declaration to specify a different implementation of the Persister interface.

Define LOCDB_USERPASS to be postgres,mypassword or whatever you have set up for database access (or edit the build file).

Apache Ant

Download and install Apache Ant. The SAND build needs to be able to find both ant.jar (core tasks) and sandbuild.jar (custom tasks). Easiest thing to do is modify your CLASSPATH environment variable to include these (e.g CLASSPATH=/Developer/Java/Ant/lib/ant.jar:$SAND_HOME/platform/sandbuild/env/sandbuild.jar... More on sandbuild.jar later on.

CVS

If you do not already have a CVS client installed, we recommend pulling down the latest from the CvsGui project and installing that.

Download SAND

To download SAND you can pull down the latest released zip file and unpack it somewhere on your drive for use. However if you want to keep up with the latest fixes and updates we recommend pulling down the latest from our sourceforge CVS server. The modulename to download is "sand" (no quotes). So for example


    cvs -z3 -d:pserver:anonymous@sandev.cvs.sourceforge.net:/cvsroot/sandev co -P sand

Then you can just update whenever you want to get the latest. Once you have the source, define the SAND_HOME environment variable to be the sand directory (e.g. /general/sand).

Build the sample project

Verify the sandbuild.jar file with the custom Ant tasks is up to date:
Verify the taskheap database exists:
If you get an error saying database "taskheap" does not exist, then
Build the sample TaskHeapDemo application:
The SANDev build process has the following stages:
1. Load: The current project and any of the projects it requires are loaded and organized in dependency order.
2. Code generation: The code generators are run according to their scope (local project, cross project, struct, node, or both).
3. Standard build: Compile, .jar, .war, javadoc for each project.
4. Deployment: .war repackaging and copying to local deployment.
The build trace has details on what code was generated, which gives an idea of how much of the TaskHeap app was written by machine.
Verify the demo app comes up:
1. open the generated $SAND_HOME/docs/index.html
2. click the "TaskHeapDemo" link in the upper left
3. click the "localhost TaskHeap webapp user interface" link in the generated page contents.
If you want to play with the TaskHeap app, you can login as admin/whatever to start. This account was defined as part of the initial data config which is also accessible from the deployment docs page. There are numerous other doc links for the project useful for development which you can explore for the apps, deployment, and platform tools used for TaskHeapDemo.

The generators in SAND run every time you build, but only write new code if struct or node declarations were actually changed. To clean up everything that was built use ant scrub.

Create your own project:


    cd $SAND_HOME/deploy/TaskHeapDemo/build 

    ant scrub 

    ant -f initproj.xml

The script will ask you a few questions and set up your project. Once it has completed, change to the deployment build directory you set up and run ant.

A typical SAND project consists of an application and a deployment. So for a project called MyApp you might have:

sand/apps/MyApp
sand/deploy/MyAppMain

each with the following subdirectories and files:

build
docs
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

@sand.structmessage

@sand.verbforms

@sand.summaryfields

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.

By default, the AuthFilter will deny all access to messages not explicitely authorized. You will need to edit the AuthFilter implementation (in the UserLookup dir) for appropriate access to each new struct you define.

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

The node declaration describes what messages are processed. Where messages are sent to and received from is set in the configuration.

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

For more information, see sandev.org.