Transform documents

From ControlTier

Transforms can process and format your Model data so that it may be reused for generating configuration files.

Transforms have two parts.

1. Transform definition. Transform definitions define the resource data to be used as input by the Transform, what template should be used, and where the output should be stored.
2. Transform Template. Transform Templates provide the instructions for how the specified data should be processed and in what format it should be outputted. Templates are user provided and can either be
   • plain text files that use a basic substitution scheme (replace hardcoded with Ant style property references)
   • or, XSLT templates can be used. XSLT Templates give you the flexibility of standard XSL and provide for such programmatic techniques as conditionals and loops.

The default implementation of Docs-Generate processes the registered transforms, producing the desired output to the specified destination paths.

Contents 1 Registering a new Document 1.1 Register via GUI 1.2 Register via a command 1.2.1 Transform Ant Tasks

Registering a new Document

There are two methods to register new transforms: via Graphical resource editor or scripted via a command.

Register via GUI

Defining a Transform in the Graphical resource editor begins by navigating to the resource for which you want to associate the document.

In the "Details" view scroll down and locate the "Documents" link and click it. That will reveal a "+ add document" button.

Figure: Add Document button

This will bring you to the first form. In this form you specify the "degree(s) away" and which dependencies to include. Typically, you just accept these defaults. Then push the "Continue..." button where you will finalize the registration.

Figure: Step 1 of creating new Transform. This step creates the View definition

During this last step you will specify the destination path information for the generated results, the type of template, and the template location. You'll notice the little magnifying glass icon next to the "Template" text field. Pressing that icon will bring you to a WebDAV browser that lets you choose a template that resides on the WebDAV. Alternatively, you can specify a path that will be local to the deployed resource. The paths can reference properties that are accessible to the resource.

Figure: Step 2 of creating new Transform. This step defines the Document and Template parameters

After completing the form you will be forwarded to a page summarizing the document definition. Click the "← Back to Object View" page to return to the resource's detail page. Once returned, you will notice that the "Documents" link will now list the newly defined document.

Register via a command

It may not be desirable or feasible to register the document transforms via the Graphical resource editor. This section describes an alternative that lets you script the document registrations via Ant tasks, in a separate command that can reside in one of your custom types.

Below is an example definition for a JBossServer [1] command called "Docs-Register" that takes a list of file names and registers them as Document transforms. The specified templates are all local to the module itself.

Once defined, this "Docs-Register" command could be invoked as the first step of the Configure workflow or perhaps in another workflow (e.g., "Prepare").

<command name="Docs-Register" description="Example: registers configuration documents required for jboss operation" 
       command-type="AntCommand"> 
<implementation>
  <!-- Register the documents generated from these templates: templates/jboss-4.0.3SP1/server/default: -->
  <for list="bindings.xml,jboss-service.xml,run.conf" param="file">
    <sequential>
      <transform-create depot="${context.depot}"
			resultproperty="transform-create.result" 
			comment="the JBoss @{file} configuration">
	<context   direction="internal" proximity="1" 
		   maprefUri="${entity.mapref-uri}"  />
	<document  type="text-plain"
		   file="@{file}" 
		   dir="${opts.basedir}/conf"  />
	<template  type="simple"
		   file="@{file}.template" 
		   dir="${module.dir}/templates/jboss-${opts.jboss_version}/server/default/conf" />
	
      </transform-create>
      <echo level="info">Registered document: @{file}.</echo>
    </sequential>
  </for>
</implementation>
<opts>
  <opt parameter="basedir" description="base directory of the jboss instance" 
       required="false" property="opts.basedir" type="string" 
       defaultproperty="entity.attribute.jboss_basedir"/>
  <opt parameter="install_root" description="" 
       required="false" property="opts.install_root" type="string"
       defaultproperty="entity.attribute.jboss_install_root" />
  <opt parameter="jboss_version" description="version of the jboss server package"
       required="false" type="string" 
       defaultproperty="entity.attribute.jboss_version" property="opts.jboss_version" />
</opts>
</command>

This example command is based on an Ant task called transform-create that registers document transforms just like one can do via the Graphical resource editor. The transform-create task is called inside the body of an Ant-contrib for loop. You will notice nested elements that together describe the Transform Document

• context: The context element defines the property data scope for this resource (entity.mapref-uri) showing just child dependency info (proximity=1, direction=internal)
• document: The document element specifies the file type (text-plain) and the output path information (file and dir)
• template: The template element specifies the kind of template (simple) and the path to the template (file and dir)

After the "Docs-Register" command completes, three documents will be defined and associated with this resource.

Transform Ant Tasks

There are a number of Ant tasks that are available for managing the registration and processing of Transforms and templates:

• Transform Task Reference
• TransformCreate Task Reference
• TransformGet Task Reference
• TemplateCreate Task Reference

v • d • e Modeler Guide Introduction Modeler Guide · Concepts · Modeler Getting started · Model-driven approach · CTL architecture · Model-driven command dispatching · File share Resource modeling Resource Model · Graphical resource editor · Graphical type editor · ProjectBuilder · Core Type Guide  · Type modeling · Attributes · Constraints Module development Module Development Guide · Modules · First type module · Workflow command · Command options Examples Creating packages · Mock Unix Service Example  · Mock Site Example  · Service Package Deployment Example  · Windows service  · Windows site  · Windows deployment · Builder Simple Example  · Continuous Deployment Example with Tomcat · Dukes Bank J2EE examples