Getting Started with Cairngen

Getting started with Cairngen is pretty simple. Begin by extracting the build directory to the root of your Flex project, or by creating a General Eclipse Project and modifying the Cairngen project.properties file to reflect your environment and project settings. If you are familiar with ANT, this will be very straight forward and you should be up and running in no time at all.

Cairngen is completely configurable. Developers can modify the Cairngorm templates, properties files and build as needed to suite their particular needs. Code generation can be viewed in real time via the console. By default details of all generated code are written to a log file in your project’s root directory, this can be disabled if desired.

Setting Up Cairngen

Setting up Cairngen is quick and easy, just follow these simple steps:

1. Download the latest release of Cairngen
2. Extract Cairngen to the location of your Flex project directory, or create a new General Eclipse project and set the project location to the directory where Cairngen has been extracted
3. Open the project.properties file and modify accordingly to reflect your projects environment.
4. Right + Click the build.xml file and select Run as > Ant build. This will run the default target which generates the typical 'com.domain.project' directories as well as the default Cairngorm folders, ModelLocator, ServiceLocator and FrontController. Ideally, if you are using Eclipse select: Window > Show View > Other > Ant, select Ant and click OK. In the Ant panel select the "Add Buildfiles" icon (first icon on left). Select Cairngen > build.xml. Expand and you will see all targets. Double click main.
5. To create sequences, edit the sequence.name property in the project.properties file (this is the name prepended to the Event, Command and Business Delegate) and any of the sequence targets.
6. To create a ValueObject edit the vo.name property and double click the "create-value-object target" or the "create-multiple-value-objects". To create multiple Value Objects simply assign a CSV (comma-delimited-list)(e.g. LoginVO, LogoutVO ...)

All Cairngorm template classes can be modified as needed. The template files are located in the build/templates/cairngorm/release directory.

Generating a Cairngorm Project

The Cairngen build file contains a default target "main" which will create the typical Cairngorm project structure:

• business
• commands
• control
• events
• model
• view
• vo

In addition the main target will also create your applications ModelLocator, FrontController and Services.mxml and generate them to the appropriate packages.

The following example demonstrates the console output when generating a Cairngorm project:

Buildfile: C:\workbench\ericfeminella\cairngen\build.xml
log:
delete-cairngorm-directories:
     [echo] @Invoking Cairngen on [CairngenExample] --> Deleting Cairngorm directories
create-cairngorm-directories:
     [echo] @Invoking Cairngen on [CairngenExample] --> Creating Cairngorm directories
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\business
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\commands
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\control
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\events
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\model
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\view
    [mkdir] Created dir: C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\vo
clean:
create-model-locator:
     [echo] @Invoking Cairngen on [CairngenExample] --> Generating file(s): ModelLocator.as
     [copy] Copying 1 file to C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\model
create-front-controller:
     [echo] @Invoking Cairngen on [CairngenExample] --> Generating file(s): CairngenExampleController.as 
     [copy] Copying 1 file to C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\control
create-service-locator:
     [echo] @Invoking Cairngen on [CairngenExample] --> Generating file(s): Services.mxml
     [copy] Copying 1 file to C:\workbench\CairngenTestProject\src\com\ericfeminella\cairngen\business
create-cairngorm-project:
main:
BUILD SUCCESSFUL
Total time: 2 seconds

Generating Events, Commands and business Delegates

Cairngen uses the term “Sequence” to describe the relationship between an Event, Command and Business Delegate (optional). The Cairngen build.xml file contains four targets for creating Sequences which are as follows:

1. create-sequence-exclude-delegate: creates an Event and Command
2. create-sequence-include-delegate: creates an Event, Command and Business Delegate
3. create-multiple-sequences-exclude-delegates: creates multiple Event and Command
4. create-multiple-sequences-include-delegates: creates multiple Event, Command and Business Delegates.

When a "sequence" is generated the FrontController is modified with an additional 'addCommand' invocation which automates the process of mapping an Event to it’s associated Command. In order to facilitate generating addCommand(); invocations the "// todo: add commands" comment in the FrontController must be present. This comment is used as a token and is replaced with an addCommand when a "sequence" is generated.

The following example demonstrates the console output when generating a "Sequence":

Buildfile: C:\workbench\ericfeminella\cairngen\build.xml
log:
add-command-to-controller:
     [echo] @Invoking Cairngen on [CairngenExample] --> Inserting addCommand in FrontController for LoginEvent and LoginCommand
add-command-to-controller-cleanup:
create-sequence-include-delegate:
     [echo] @Invoking Cairngen on [CairngenExample] --> Generating file(s): LoginEvent.as, LoginCommand.as, LoginDelegate.as
     [copy] Copying 1 file to C:\workbench\clients\CairngenTestProject\src\com\ericfeminella\cairngen\events
     [copy] Copying 1 file to C:\workbench\clients\CairngenTestProject\src\com\ericfeminella\cairngen\commands
     [copy] Copying 1 file to C:\workbench\clients\CairngenTestProject\src\com\ericfeminella\cairngen\business
BUILD SUCCESSFUL
Total time: 1 second

Generating Value Objects (VOs)

Cairngen provides targets for generating both single and multiple Value Objects. The two targets which generate ValueObjects are:

1. create-value-object: generates a single Value Object
2. create-multiple-value-objects: generates multiple Value Objects

The following example demonstrates the console output when generating a Value Objects:

Buildfile: C:\workbench\ericfeminella\cairngen\build.xml
create-value-object:
     [echo] @Invoking Cairngen on [CairngenExample] --> Generating file(s): Login.as
     [copy] Copying 1 file to C:\workbench\clients\CairngenTestProject\src\com\ericfeminella\cairngen\vo
BUILD SUCCESSFUL
Total time: 422 milliseconds

Cairngen Properties