The Alchemist Quick Start Guide

The standard CTC Software distribution can now produce a web application that can be used to create new models.

This document describes how you can get started. [Additional help is available on the howtos page.]

It should take between one and two hours to work through the paper, depending on whether or not you already have java, tomcat and ant installed. I appreciate that this involves some commitment on your part, but it'll be worth it.

Stage 1: Download the distribution

From the main downloads page get the Full Distribution download, this has recently been reduced to just a 1.9MB zip file.

Unzip it into a target directory, and set the environment variable CTC_ENV to reference it.

Stage 2: Ensure recent Java SDK distribution

Any version greater than 1.4 should be fine, get the latest from here.

You'll need the SDK rather than just the JRE. Be sure to add the bin directory to your path and set the JAVA_HOME environment variable to point to the install directory.

Stage 3: Download and install recent Tomcat

You need a "servlet container" to host the web application. You can get the latest from here.

Set the TOMCAT_HOME environment variable to point to the install directory.

Stage 4: Download and install recent Ant distribution

You can get the latest from here. Set the ANT_HOME environment variable to point to the install directory.

Stage 5: Generate and install the Alchemist web application

If everything is set up correctly, then open a command window, navigate to the CTC_ENV directory and then "cd" to the "alchemist" directory.

Enter:

ant

and hit return.

This should create the alchemist.war file and copy it to the tomcat/webapps folder.

If you have any problems re-check the configuration in the previous steps.

If you still have problems, then feel free to mail me with as much information as possible.

Stage 6: Starting the Web Application

Start tomcat.

Open a browser - Mozilla recommended - and enter the URL:

http://localhost:8080/alchemist

Performance Note The web application is defined by a number of JSP files. The first time each is accessed it is processed to generate java code and must be compiled. This initial access of each page will cause a delay (a few seconds), but thereafter should not be noticable.

The Alchemist Web Application

When the Alchemist starts up you should see the following screen:

The application introduces itself, the "Model" and "Help" panes describe the Alchemist "Model" and provide "Help" on the way the web application should be used.

You should be aware that this specific web application follows the same structure as those applications that will eventually be generated - in fact this application has also been generated in large part.

Select the "Workspace":

The Alchemist Workspace

The screen is divided into four identifiable areas, top-left is the "control panel".

From this panel you can navigate to either the "Main Screen" or "Inspector" view.

You should also note the "trash can". You can use the "trash can" to remove objects by dragging references to them into it.

The three remaining areas each host a separate "inspector" view, initially each will look something like this:

If the CTC_ENV field is blank you should enter the location of the distribution directory. The web application will need this information later on.

When you first edit the values you will see a Submit Update button appear. When you are finished editing, click on it.

When your update is accepted you will see two buttons appear in the control panel, these determine the final update to the underlying datastore, you may submit many updates before choosing to finally "Save" the modifications.

Create A New Model (ORM)

The Alchemist models are known as "ORMS" - Object Representation Models.

In the Inspector pane you will find an ORMs tab, select it:

When you first access this list there will be no members, select Create ORM and create a new ORM called "Contacts" and with a package "alchemy.contacts".

Once created the pane will focus on the newly create ORM.

Now, in exactly the same way that you have just created an ORM from the Alchemist you can create the classes and association that will make up the "Contacts" ORM.

Create The Root "AddressBook" Class

Our Contacts system will initially define an AddressBook that will maintain a list of Contacts, so first create a new class called "AddressBook".

The Inspector will focus on the newly created object:

Check the "isRoot" option and enter some documentation on the class. Selecte "Submit Update" and "Save" the state.

Create the "Contact" Class

Re-focus on the "ORM" by clicking the ORM "Contacts" reference, select the "CClasses" tab (you will see that you now have an "AddressBook" class), and create a new "Contact" class.

Create an Attribute

Select the "Attributes" tab for the "Contact" class, create a new "Attribute" called "Name" and with type "java.lang.String":

The Inspector will then focus on the create attribute;

Check the "isLabel" and "required" options. The "label" option means that whenever an instance of Contact is displayed it will use the value of the Name attribute as a "label". The "required" option indicates that whenever an instance is created it must be provided with a value for its "Name".

Create an Association

In another Inspector pane focus on the "Contacts" ORM, select the "Associations" tab and create a new Association:

Okay, now for the cool bit! In another Inspector, focus on the "Contacts" ORM and select the "Classes" tab.

"Drag and Drop" the "AddressBook" class onto the "source" field, and the "Contact" class onto the "target" field, then create the association.

The new Association will now be focussed.

Check the "isOwner" option. This indicates that the "AddressBook" is the "owner" of the "Contact" instances. This is taken to mean that the "AddressBook" as well as having a one-to-many association with "Contact" instances, should also "create" them.

In the "TrgtLookup" field enter "Name:alpha". This indicates that the set is classified using the value of the "Name" property, with a hint that the values are alphabetical.

Submit and Save the modifications.

First Play

Okay, that wasn't too hard, but let's see directly how the model is developing.

Focus on the "Contacts" ORM and select the "Generation" tab:

At this stage we have defined an initial model, so let's see what happens when we choose the first option "An Immediate AddressBook System".

Since we have not defined any attributes for the AddressBook class there are none to display. You can create an attribute in another inspector and then refresh the current inspector by clicking on the AddressBook:AddessBook#15 at the inspector top-left.

Try creating a "Name" attribute and indicating that it should be used as a label.

Have a play and see what happens. Does it make sense?

Right, now you are ready to create a "Contact", choose the "Contacts" tab and create one.

You should now realise that this is just what you have been doing within the Alchemist itself, except that now you are creating "Contacts" objects.

Okay, I have create a contact named "Martyn" - not very imaginative but the first name that came to me.

Now, let's create some more attributes for our new "Contact". In another Inspector, locate the "Contact" class and create a new Attribute, say "Address". Refresh the "Contact" view:

...hmmmm, okay, but most addresses will need more than a single line. Edit the "Address" attribute:

The field "GuiHint" is used by the web application to provide some "hint" on how the field should be displayed.

Now create two more attributes. "Email" and "Website". For the "Email" attribute set the "GuiHint" and "Restriction" to the value "email", and for the "WebSite" attribute to the value "url". Submit the updates and then refresh the "Contact" view:

This is starting to look more promising.

The "email" field will only accept a valid "email", and the icon can be used to send an email to that address.

Similarly, the "Website" field will only accept a valid URL and the icon will open a new browser window on the site indicated.

Incremental Development

You may continue to develop the "Contacts" model and create new models of you own.

Quick Hints

When declaring attributes of type Date the Web Application will create a special edit control:

The arrow keys are accelerated meaning that as you continue to hold them down the size of the increments increases.

The "lookup" specification has a few options:

The calendar hint renders a calendar view with dates that can be dragged and dropped onto Date property values.

In the Contacts example you could create a Meetings class classified by both Name and by declaring the TrgtLookup on the Contacts-Meeting association to be Subject:alpha;Date:calendar, this would generate the following lookup views:

and

Restrictions: You will find a restrictions.xml file under CTC_ENV/src/alchemy. In that are alias declarations that map short named restrictions to their regular expression definitions. You are free to modify these declarations and add new ones.

GuiHints: There are a limited number of GuiHints currently supported.

...and then?

When you are happy that the model seems usable, you should generate The java code for the object model from the "Generation" tab of the ORM.

Once generated the output from the process will be reported back:

It will tell you where you will find the generated source code, show you the output from the build, and provide a link that will take you to the newly installed web application (but make sure to give the webserver a few seconds to complete the installation).

Customization

The new web application can be customized by defining forms and views to be associated with specific object instances. A future whitepaper will focus on these mechanisms, but you can investigate the Alchemist web application itself - check out the forms and views directories and the custom/login.jsp file.

Enjoy!