ControlTier > core
 
 
PDF -icon
PDF

ProjectBuilder

ProjectBuilder is a utility type to assist developing and loading of source-based projects in the ControlTier system.

Overview

ProjectBuilder: ProjectBuilder is a utility type to assist developing and loading of source-based projects in the ControlTier system.

Formats for load-objects

Project XML format

Project XML documents are used both to specify the bulk loading of objects as well as define the format of dumps of sections of a Workbench project's object model.

The project XML document type (DTD) defines the most general XML mapping of the object model. The project.dtd and sample.xml files can be found in the "lib/load-objects/projectxml" directory of ProjectBuilder

Any number of objects can be defined in a given document. Each object is represented by one of the four base type elements: node, setting package and deployment. Each object of a given base type is identified by the required type and name attributes.

Note that unique object names by type are assumed, and that each file may reference a particular object only once. This means that the project XML format is not usable with modules that allow non-unique object names

When defining an object, it is unnecessary to specify all attributes beyond name and type. The system will preserve existing attribute values, or leave unspecified attributes of a new object unset. It is therefore possible limit the XML definition of an object to the type, name and only those optional attributes whose values must be changed.

The dependencies between objects are represented by the "resources" and "referrers" sub-elements. The "replace" attribute determines whether pre-existing resource and referrer relationships are preserved with the new being added, or whether they are wholly replaced by the new dependencies.

If the replace attribute is omitted, the resource and referrer dependencies are not replaced by those specified in the XML (i.e. the new dependencies supplement the existing configuration).

Note that batch operations associated with resources of all objects specified by the project XML are executed before those associated with referrers. This has particular relavence when replacing referrers since great care must be taken to ensure that a comprehensive set of replacements are provided. It is not sufficient to rely on the same dependency being specified as a resource relationship elsewhere in the project XML (or even more subtly to imagine that not replacing resource relationships for the parent object will automatically preserve the relationship from the referrer perspective).

Just remember that resources and referrers are two halves of the same relationship tieing the object model together as a whole!

However, if no resource or referrer dependencies are specified in the XML, then existing relationships are left undisturbed.

The "resource" sub-element identifies particular objects by type and name. These objects do not necessarily have to be defined in the XML document given that they already exist in the object model.

In general, semantic validation is left to the Workbench type model's constraint checking. Note that since new objects are created during processing of the document while updates are batched for execution once document processing is complete, a validation error at any point will leave the object model partially updated. i.e. there is no transactional integrity across the processing of a single document that contains new objects.

The net effect of this will be to leave extraneous new objects in the model.

However, documents that consist only of pre-existing objects will only use the batch update interface. Failures in this case are completely rolled back leaving the object model unchanged.

Tabular format

The tabular format is a delimited data format that has columns separated by the -delimiter argument value and records separated by newlines. Any character string can be used as a delimiter but the : (colon) character is default. Currently, there are two kinds of 'table' files used to declare instances of Deployment and Setting subtypes. A third can be used to declare object to object dependencies.

An example set of .tab files in a module directory structure are shown below:

  • TypeX/
    • type.xml
    • commands/
    • objects/
      • binding.tab
      • deployment.tab
      • setting.tab
    • templates/

Each format uses a different set of columns described as follows:

Deployments

The deployment tabular format is used to define instances of Deployment subtypes.

Format 
		  # deployment.tab format -
		  # type:name:install-root:basedir:rank:description
		  Apache:staging:/usr/local/apache2:/var/apache:3:the staging instance
Example command usage 
ctl -p project -t ProjectBuilder -o object -c load-objects -- \
	  -type TypeX -filename deployment.tab  -basetype deployment
Settings

The setting tabular format is used to define instances of Setting subtypes.
Format 
	    # setting.tab format -
	    # type:name:settingValue:settingType:description
	    ApacheDocroot:commonDocroot:/docroot:documentRoot:web docroot
Example command usage 
ctl -p project -t ProjectBuilder -o object -c load-objects -- \
	  -type TypeX -filename binding.tab  -basetype setting
Bindings

The binding tabular format is used to define object child dependencies.

Format 
	    # binding.tab format -
	    # parentType,parentName:childType,childName
	    # Apache -> ApacheSetting
	    Apache,staging:ApacheDocroot,commonDocroot
Example command usage 
ctl -p project -t ProjectBuilder -o object -c load-objects -- \
	  -type TypeX -filename binding.tab  -basetype binding

Design

Super Type
Builder
Role Concrete. (Objects can be created.)
Instance Names Unique
Notification false
Template Directory
Data View Children, proximity: 1
Logger Name ProjectBuilder

Constraints

Allowed Child Dependencies

1: These types have a Singleton constraint. Only one instance may be added as a resource.

Allowed Parent Dependencies

Attributes

Note
ProjectBuilder uses a number of attributes to parameterize its commands. The basedir and targetdir options will be defaulted to the values of those attributes. Most of the command examples shown in this document show off this defaulting behavior.

Defaults for Imported Attributes

Name Default Description
buildFile ${modules.dir}/ProjectBuilder/lib/build.xml Default build file run by runBuildScript.
buildTarget all

Specifies what build target(s) to invoke for buildfile

defaults ${modules.dir}/ProjectBuilder/templates/defaults.properties
importMin 0
organizationDescription Maker of the ControlTier software
organizationName ControlTier
organizationURL http://www.controltier.com
packageExtension jar
packageFilebase .*-seed
packageType jar
projectDescription The ControlTier base types
projectName ${context.name}
projectURL http://open.controltier.com
stageextension jar
stagefilebase .*
subdirs doc,jobs,modules,objects
templateDir ${modules.dir}/ProjectBuilder/templates

Commands

Command Overview

Given the number of commands available with ProjectBuilder, it may be difficult to get an overall view of what each command can do. The following table groups the commands into several categories and provides a link to the command's documentation.

Development Utilties create-type, build-type, refactor-rename, convert-rdf
Data Utilties generate-objects, load-objects, find-objects, purge-objects
Builder commands build-library, generate-forrest-docs, load-types, runBuildScript
Jobcenter commands load-jobs,find-jobs

View the available commands in the User Reference.

Related Types

The following types are defined for use with ProjectBuilder.

ProjectBuilderBuildTarget

Overview

ProjectBuilderBuildTarget: Build target for ProjectBuilder

The runBuildScript command invokes the specified buildfile to execute the project build cycle.

By default, ProjectBuilder uses the Ant build file: ProjectBuilder/lib/build.xml. This build.xml provides a set of targets:

Target Description
all Calls targets: clean, library and docs
clean Removes the targetdir contents
library Runs the build-library command to build all types and package them into a library.
docs Runs the generate-forrest-docs command to generate a documentation site.
objects Runs the load-objects command to load available object data for the types.

Users wishing to extend or implement their own project build cycle can develop a build.xml of their own and create an object dependency to an instance of BuilderBuildFile that contains the path to the file.

Likewise, user specific build targets can be specified using an instance of BuilderBuildTarget.

Design

Super Type
BuilderBuildTarget
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies
Allowed Property Values
Property Allowed Values Default Enforced
settingValue
  • all
  • clean
  • docs
  • jobs
  • objects
  • types
false

Attributes

Exported Attributes
Name Property
buildTarget settingValue

ProjectBuilderDefaults

Overview

ProjectBuilderDefaults: file containing project defaults properties

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Attributes

Exported Attributes
Name Property
defaults settingValue

ProjectBuilderDocBase

Overview

ProjectBuilderDocBase: Path to documentation directory

Design

Super Type
Setting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
docbase settingValue

ProjectBuilderForrestHome

Overview

ProjectBuilderForrestHome: Path to FORREST_HOME directory

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
forresthome settingValue

ProjectBuilderOrganizationDescription

Overview

ProjectBuilderOrganizationDescription: Descrpiton of organization responsible for the project

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
organizationDescription settingValue

ProjectBuilderOrganizationName

Overview

ProjectBuilderOrganizationName: Organization responsible for the project

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
organizationName settingValue

ProjectBuilderOrganizationURL

Overview

ProjectBuilderOrganizationURL: URL to the organization home page

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
organizationURL settingValue

ProjectBuilderProjectDescription

Overview

ProjectBuilderProjectDescription: Brief description about the purpose of the project

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
projectDescription settingValue

ProjectBuilderProjectName

Overview

ProjectBuilderProjectName: The project name

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
projectName settingValue

ProjectBuilderProjectURL

Overview

ProjectBuilderProjectURL: URL to the project home page

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

Attributes

Exported Attributes
Name Property
projectURL settingValue

ProjectBuilderSetting

Overview

ProjectBuilderSetting: An abstract ProjectBuilder setting

Design

Super Type
Setting
Role Abstract. (Objects cannot be created.)
Instance Names Unique

Constraints

Allowed Parent Dependencies

ProjectBuilderTemplateDir

Overview

ProjectBuilderTemplateDir: file containing project template files

Design

Super Type
ProjectBuilderSetting
Role Concrete. (Objects can be created.)
Instance Names Unique

Attributes

Exported Attributes
Name Property
templateDir settingValue