From ControlTier

Jump to: navigation, search

This document describes the XML tags used to define a ControlTier type. See the Core Type Guide for existing types. Use ProjectBuilder or the Graphical type editor to create and manage a type definition.

types

The root (aka "top-level") element of the type.xml file. Contains a set of #type elements. Any kind of type can be specified in any order.

<?xml version="1.0" encoding="UTF-8"?>
 
<types xmlns:cmd="http://open.controltier.com/base/Modules/Commands#" 
       xmlns:module="http://open.controltier.com/base/Modules#" 
       xmlns:type="http://open.controltier.com/base/Types#">     
 
       <type ...>
          ...
        </type>
  </types>

type

The type element defines a Type and command module. If the "order" attribute is "Setting" or "Assembly", then the elements required to define the command Module are not required.

attributes
attribute	description	values
name	Name of the type
role	Specifies the role of the type. Concrete means it can be instatiated as objects. Abstract specifies it cannot be instantiated.	"concrete" or "abstract"
order	Name of a well known base type.	Setting, Assembly, Deployment, Service, Mediator
uniqueInstances	A boolean signifying if each instance of the type must have a unique name. "false" is default.	true or false

nested elements
element	description
description	Text content describing the type
#supertype	Reference to the parent type
#command-settings	Properties of the command module

<type
        name="TypeName"
        role="concrete"
        order="TypeName"
        uniqueInstances="true">
 
        <description>describe the type</description>
 
        <supertype>
            <typereference name="TypeName"/>
        </supertype>
 
	...
   </type>

doc

A documentation block. Can contain any valid Apache Forrest xdoc tag. The doc tags can be used just about anywhere in the type.xml. When ProjectBuilder's generate-forrest-docs command is run, the doc tags are expanded into the generated forrest xdocs.

See Generating Forrest Sites for more information.

supertype

A sub-element of #type, supertype specifies the parent type of this type. A typereference tag is used to specify the supertype by name.

nested elements
element	description
#typereference	Text content describing the type

  <supertype>
            <typereference name="TypeName"/>
  </supertype>

typereference

Specifies a type.

attributes
attribute	description	values
name	Name of the type	Any existing type.

command-settings

Properties of the command module

nested elements
elements	description	values
notification	Advisory setting stating if notofications are enabled. Specify the `notify` attribute with a boolean value.	"true" or "false"
template-directory	path to template directory	Any valid path. By convention it is `${module.dir}/templates`
#dependency-view	Paramaters to used when retrieving resource model view	See #dependency-view
logger	Name used by log calls	By convention, the type name

<command-settings>
         <notification notify="false"/>
         <template-directory></template-directory>
         <dependency-view parents="false" children="true" proximity="1"/>
         <logger name="TypeName"/>
     </command-settings>

dependency-view

Paramaters used as defaults for the Get-Properties command options

attributes
attribute	description	values
parents	Include parent dependency info	"true" or "false"
children	Include children dependency info	"true" or "false"
proximity	Number of levels away from the source object	1, 2, 3, 4

attributes

define attributes of the Type here. type-property values are the names of properties in the depo: namespace

nested elements
elements	description
#attribute	Attribute declaration
#attribute-default	These will be generated into type.properties

 <attributes>
       <attribute name="attr_name" type-property="property-name"/>
       <attribute-default name="attr_name" value="VALUE"/>
    </attributes>

attribute

Declares an attribute.

attributes
attribute	description	values
name	Attribute's name	Any name. (avoid whitespace)
type-property	Associated RDF property	See #RDF-props for a list

attribute-default

Defines a default value for a declared attribute via the #attribute element.

attributes
attribute	description	values
name	Attribute's name	Name of declared attribute
value	Attribute's default value.	Any string value

constraints

A sub-element of #type. Type constraints are used to control the allowed kinds of dependencies (both parent and child). Also controls the allowed values for its RDF properties.

nested elements
elements	description
#allowedvalue-constraint	Contains any number of #allowedvalue elements
#dependency-constraint"	Specifies #allowedtypes and #singletontypes

Several examples of constraints: allowed-value, dependency-constraint:

<constraints>
            <allowedvalue-constraint
                enforced="true/false"
                type-property="depo-property-name">
                <allowedvalue value="<SOME VALUE>" default="true/false"/>
                <allowedvalue value="<SOME VALUE>" default="true/false"/>
            </allowedvalue-constraint>
 
            <dependency-constraint kind="parent/child" enforced="true/false">
                <allowedtypes>
                    <typereference name="<TYPE NAME>"/>
                    <typereference name="<TYPE NAME>"/>
                </allowedtypes>
                <singletontypes>
                    <typereference name="<TYPE NAME>"/>
                    <typereference name="<TYPE NAME>"/>
                </singletontypes>
            </dependency-constraint>
</constraints>

allowedvalue-constraint

Contains any number of allowed values.

attributes
attribute	description	values
enforced	Specifies if the constraint should be enforced	"true" or "false"
type-property	Name of RDF property.	See #RDF-props for a listing.

nested elements
elements	description
#allowedvalue	An `allowedvalue` element

<allowedvalue-constraint
                enforced="false"
                type-property="package-install-root">
     <allowedvalue value="/opt/foo"/>
     <allowedvalue value="/usr/local/foo"/>
     <allowedvalue value="/usr/share/foo" default="true"/>
</allowedvalue-constraint>

allowedvalue

An allowed value.

attributes
attribute	description	values
value	An allowed value	Any string
default	Specifies if it should be the default value.	"true" or "false"

dependency-constraint

Defines relationship constraints for the type.

attributes
attribute	description	values
kind	Kind of dependency.	"parent" or "child"
enforced	Specifies if the constraint should be enforced	"true" or "false"

 <dependency-constraint kind="child" enforced="true">
                <allowedtypes>
                    <typereference name="TypeA"/>
                    <typereference name="TypeB"/>
                </allowedtypes>
</dependency-constraint>

nested elements
elements	description
#allowedtypes	Set of allowable types
#singletontypes	Set of allowable singleton types

allowedtypes

Specifies which types are allowed to have a dependency relationship.

nested elements
elements	description
#typereference

singletontypes

Specifies which types are allowed to have a singleton dependency relationship (i.e., cardinality is 0 or 1).

nested elements
elements	description
#typereference

commands

A sub-element of type, the commands element contains the command definitions for this type. See the Workflow Development Guide for more information about developing commands for types.

<commands>
       <command name="<COMMAND NAME>"
                description="<COMMAND DESCRIPTION>"
                 command-type="{Command|AntCommand|BsfCommand|WorkflowCommand|DispatchCommand}">
             <opts>
                <opt parameter="<OPT NAME>"
                     description="<OPT DESCRIPTION>"
                     required="{true|false}"
                     property="opts.<OPT NAME>"
                     type="{string|boolean}"
                     default="<DEFAULT STRING VALUE>"/>
               </opts>
           </command>
	 </commands>

command

Defines a command for the type.

attributes
attribute	description	values
name	The command's name	Any string
description	Breifly describe the command purpose.	Any string
command-type	The type of command implementation	See #command-type for a list of known command types
is-static	A static command is one that can run outsidef of an object context	"true" or "false"
daemonized	Should the executable be launched in daemon mode?	"true" or "false"
is-private	A private command is not inherited by sub types (since ControlTier 3.4.7)	"true" or "false"

nested elements
elements	description
#opts	Specifies the commands options
#execution-string	Specifies the file to execute for a "Command" command-type
#argument-string	Specifies the arguments for a "Command" command-type
#implementation	Specifies the implementation for an "AntCommand" command-type
#script	Specifies the implementation for a "BsfCommand" command-type
#workflow	Specifies command sequence for a "WorkflowCommand" command-type
#error-handler	Specifies an error handler. Only "WorkflowCommand" and "DispatchCommand" command-type.
#success-handler	Specifies a success handler. Only "WorkflowCommand" and "DispatchCommand" command-type

command-type

An attribute for the #command element that specifies the type of command implementation.

Command: A command implemented as a shell execution
BsfCommand: A command implemented using the BeanShell Scripting Framework
AntCommand: A command implemented using Ant tasks
WorkflowCommand: A sequence of defined commands
DispatchCommand: Relays a command to matching resources.

execution-string

File to execute. Used by command-type Command. See: Shell command in the Workflow Development Guide.

argument-string

Arguments to pass to executable. If the execution-string specifies an interpreter that can read script from stdin, the value of argument-string can be script code. See: Shell command in the Workflow Development Guide.

implementation

Ant tasks to execute. See: Ant command in the Workflow Development Guide.

script

BSF script to execute. See: BSF command in the Workflow Development Guide.

workflow

Command sequence to execute. Takes one more more command elements. See: Workflow command in the Workflow Development Guide.

attributes
attribute	description	values
threadcount	Number of threads to execute the workflow	Any integer greater than 0
error-handler-type	Type of error handler to invoke when a subcommand fails	One of: "IGNORE", "HANDLER", or "FAIL"

nested elements
elements	description
command	Name of the command. Command must be in the same module.

 <command name="<WORKFLOW COMMAND NAME>"
                  description="<WORKFLOW COMMAND DESCRIPTION>"
                  command-type="WorkflowCommand"
                  error-handler-type="HANDLER | IGNORE | FAIL"
                  >
           <error-handler quiet="true/false">
             <prompt>PROMPT MESSAGE</prompt>
             <command name="<ERROR HANDLER COMMAND NAME>"/>
             <notify email="NAME@HOST">
               <subject>SUBJECT</subject>
               <message-file>PATH</message-file>
             </notify>
             <report>REPORT MESSAGE</report>
           </error-handler>
           <success-handler notify-email="NAME@HOST">
             <notify-subject>SUBJECT</notify-subject>
             <notify-message-file>PATH</notify-message-file>
           </success-handler>
           <workflow threadcount="<INTEGER>">
             <command name="<COMMAND NAME>"/>
             <command name="<COMMAND NAME>"/>
           </workflow>
         </command>

dispatch-command

Dispatch commands to the selected contexts. Takes one more more command elements. See: Dispatch command in the Workflow Development Guide.

attributes
attribute	description	values
name	Workflow name	defaults to command.name
requirematch	Requires one or more matches	true (default)
strategy	Execution strategy	"localdispatch" or "nodedispatch"
threadcount	Number of threads to execute the workflow	Any integer greater than 0
error-handler-type	Type of error handler to invoke when a subcommand fails	One of: "IGNORE", "HANDLER", or "FAIL"

nested elements
elements	description
#arg	The argument line.
#command	The command to dispatch.
#contexts	The object contexts to execute the command. Can contain one of #select-dependencies, #select-deployments, #select-resources

 <command name="name"
                  description="description"
                  command-type="DispatchCommand"
                  error-handler-type="HANDLER"
                  >
           <error-handler quiet="false">
             ...
           </error-handler>
 
           <dispatch-command threadcount="1" 
	                     requirematch="true"
             >
             <command name="dispatchedCommand"/>
             <arg line="argLine"/>
             <contexts>
	       <select-deployments sortkey="name" sortorder="ascending" depot="${context.depot}">
	         <include name=".*" type="[^\.]*"/>
	       </select-deployments>
             </contexts>
           </dispatch-command>
         </command>

include

Object include filter

attributes
attribute	description	values
name	Object name	regex
type	Object type	regex

select-dependencies

Object include filter based on object dependencies declared in properties. Accepts one #include nested element.

attributes
attribute	description	values
relationtype	Object's base type	regex
sortkey	Object property used as sort key
sortorder	Sort order	"descending" or "ascending" (default)
source	Data source to read property data	"file" or "context" (default)

<select-dependencies sortkey="startup-rank"
 			     sortorder="descending"
 			     relationtype="deployment" source="context">
 	  <include name="me[12]" type="Managed-.*"/>
 	</select-dependencies>

select-deployments

Looks up dispatch targets from the resources.properties file. Accepts one #include nested element.

attributes
attribute	description	values
depot	project name name	an existing project
sortkey	Object property used as sort key
sortorder	Sort order	"descending" or "ascending" (default)

<select-deployments sortkey="startup-rank"
 			     sortorder="descending"
 			     depot="${context.depot}">
 	  <include name="me[12]" type="Managed-.*"/>
 	</select-deployments>

select-resources

Looks up dispatch targets from the specified project. Accepts one #include nested element.

attributes
attribute	description	values
depot	project name name	an existing project
sortkey	Object property used as sort key
sortorder	Sort order	"descending" or "ascending" (default)
source	Data source to read property data	"file" or "context" (default)

<select-resources sortkey="startup-rank"
 			     sortorder="descending"
 			     depot="${context.depot}">
 	  <include name="me[12]" type="Managed-.*"/>
 	</select-resources>

error-handler

Handles an error if one occurs

attributes
attribute	description	values
quiet	Log a message if an error is caught?	"true" or "false"
errorproperty	Name of property to set error message	string

nested elements
elements	description
prompt	Prompt user if an error occurs
command	Run the specified command. Must be in the same module.
notify	Send an email.
report	Call the `report` task with the error message.

Example

 <error-handler quiet="true">
             <prompt>PROMPT MESSAGE</prompt>
             <command name="aCommand"/>
             <notify email="NAME@HOST">
               <subject>SUBJECT</subject>
               <message-file>PATH</message-file>
             </notify>
             <report>REPORT MESSAGE</report>
 </error-handler>

opts

Specifies the commands options

nested elements
elements	description
#opt	Defines one option for the command

                <opt parameter="<OPT NAME>"
                     description="<OPT DESCRIPTION>"
                     required="{true|false}"
                     property="opts.<OPT NAME>"
                     type="{string|boolean}"
                     default="<DEFAULT STRING VALUE>"
                     defaultproperty="<PROPERTY NAME>"
                  />

opt

Specifies one command option.

attributes
attribute	description	values
parameter	The option's name	Any string
description	Breifly describe the option's purpose.	Any string
required	Breifly describe the option's purpose.	"true" or "false"
property	Name to set the option value	By convention it is opts.parameter
type	Type of parameter. A string option is one that takes an argument. A boolean option does not.	"string" or "boolean"
default	Literal value to use if the option is not specified.	Any string
defaultproperty	Property name to use if the option is not specified.	Any property that may exist at execution time.

RDF-props

Attribute constraints can control the allowed values and defaults for the RDF properties of base types. The following is a listing of ones that can have constraints applied.

name	description	domain
deployment-basedir	Deployment base directory	Deployment
deployment-install-root	Deployment installation root directory	Deployment
deployment-startup-rank	Deployment startup rank	Deployment
os-arch	Operating system architecture	Node
os-family	Operating system family (windows, unix)	Node
os-name	Operating system name	Node
os-version	Operating system version	Node
package-arch	Package architecture	Package
package-base	Package base name	Package
package-buildtime	Package build time	Package
package-filename	Package file name	Package
package-filetype	Package file type	Package
package-install-rank	Package install rank	Package
package-install-root	Package install directory	Package
package-release	Package release identifier	Package
package-release-tag	Package release tag	Package
package-repo-url	URL to the package in the repo	Package
package-restart	Boolean flag specifying if a restart is required (true,false)	Package
package-version	Package version	Package
settingValue	Holds the setting value	Setting
settingType	User defined type definition of the setting value	Setting

Set the allowedvalue-constraints for the RDF properties package-restart and package-install-root:

<constraints>
       <allowedvalue-constraint
                enforced="true"
                type-property="package-restart">
                <allowedvalue value="true"/>
                <allowedvalue value="false" default="true"/>
        </allowedvalue-constraint>
       <allowedvalue-constraint
                enforced="false"
                type-property="package-install-root">
                <allowedvalue value="/opt/foo"/>
                <allowedvalue value="/usr/local/foo"/>
                <allowedvalue value="/usr/share/foo" default="true"/>
        </allowedvalue-constraint>
</constraints>

Type-v10.xml