Converting Workbench modules for use with ProjectBuilder

From ControlTier

These instructions only pertain to ControlTier 3.4.8 installations (and earlier). Workbench 3.4.9 automatically generates type.xml when packaging a module.

ProjectBuilder allows architects and administrators to manage their projects as a set of (XML) sources using development tools of choice as opposed to solely using Workbench.

Some people already have sets of modules created under Workbench and therefore need to convert them for use with ProjectBuilder.

This document is a quick explanation on how to make this conversion using the convert-rdf command.

Contents 1 Setup 1.1 Register 1.2 Create Sources Directory 1.3 Generate module JAR 1.4 Retrieve the module JAR 2 Convert 3 Test

Setup

Setup a minimal ProjectBuilder object for your project. By convention, the ProjectBuilder is given a library name ("mylib" in this case) that reflects the combined intent of the set of modules it manages.

Register

The command below registers a new ProjectBuilder object and installs it to the local CTL instance.

The "-basedir" option specifies the parent directory where the module sources reside. The "-targetdir" specifies where the generated artifacts will be stored.

ctl -p demo -t ProjectBuilder -o mylib -c Register -- \
  -basedir \${env.CTIER_ROOT}/src/mylib -installroot \${env.CTIER_ROOT}/target/mylib -install
.
.
.
[command.timer.Deployment.Register: 4.123 sec]

It's important to know that the ProjectBuilder commands assume a "modules" subdirectory below the basedir and below that your module source.

Example:

${env.CTIER_ROOT}/src/mylib
  |
  `--modules
       |
       |-- MyBuilder
       |-- MyService
       ...
       `-- MySite

By the way, the base directory is usually put under source code control to provide version management for the module source.

Create Sources Directory

Create the minimal base directory structure:

mkdir -p $CTIER_ROOT/src/mylib/modules

Generate module JAR

For each type you want to convert, generate a module JAR for it in Workbench. Workbench will generate the module artifacts and store it as a JAR file in the WebDAV.

Navigate to your type and press the "Package Commands" button.

The generated artifacts are now prepared as a module JAR.

Retrieve the module JAR

Use the "Install-Module" command to pull the generated JAR from the WebDAV and expand it to the local depot modules directory:

ctl -p demo -t ProjectBuilder -o mylib -c Install-Module -- -module MyService
Getting: http://strongbad:8080/jackrabbit/repository/workbench/demo/publish/modules/MyService-head.jar
To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/MyService-head.jar
Created dir: /Users/alexh/ctier/ctl/depots/demo/modules/MyService
Expanding: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/MyService-head.jar into /Users/alexh/ctier/ctl/depots/demo/modules/MyService
.
.
.

Copy the expanded module to your source directory:

cd $CTIER_ROOT/src/mylib/modules
cp -r /Users/alexh/ctier/ctl/depots/demo/modules/MyService .

Note: Depending on your configuration the module might have been installed in $CTL_BASE/modules

Convert

Convert the module's RDF files to type XML format using the convert-rdf command :

ctl -p demo -t ProjectBuilder -o mylib -c convert-rdf -- -type MyService
Converting: /Users/alexh/ctier/src/mylib/modules/MyService/type.rdf and 
/Users/alexh/ctier/src/mylib/modules/MyService/module.rdf => /Users/alexh/ctier/src/mylib/modules/MyService/type.xml

Remove extraneous RDF and property files from the module source:

rm MyService/*.rdf MyService/*.properties

Those files will be generated by the ProjectBuilder "build-type" command every time it is run and do not need to be maintained in the sources.

Test

Test building the module from source and uploading it to the project via build-type. Specify the the "-type" parameter to name your type and the "-upload" flag to indicate it should be reloaded to Workbench.

ctl -p demo -t ProjectBuilder -o mylib -c build-type -- -type MyService -upload

You should see messages resembling the output below:

Created dir: /Users/alexh/ctier/target/mylib/modules
Building type using the buildmodule.xml via classloader
converting type.xml for module: MyService
generating handlers...
packaging module: MyService
Copying 1 file to /Users/alexh/ctier/src/mylib/modules/MyService
Copying 1 file to /Users/alexh/ctier/src/mylib/modules/MyService
Deleting: /Users/alexh/ctier/src/mylib/modules/MyService/module.properties.temp
Building jar: /Users/alexh/ctier/target/mylib/modules/MyService-1.jar
Uploading built module to server ...
processing files in directory: /Users/alexh/ctier/target/mylib/modules
scanning for files matching pattern: (MyService)-([0-9]+)\.jar
Uploading jar: /Users/alexh/ctier/target/mylib/modules/MyService-1.jar to server: 'strongbad' ...

Go back to Workbench and view your type definition again.

With care you can go back and forth between ProjectBuilder and Workbench but we consider it best practice to use ProjectBuilder for operational projects.