N1 Service Provisioning System 4.1 Reference Guide

Chapter 1 An Overview of N1 Service Provisioning System Software XML Schemas

The plan and component language or XML schema defines the syntax and semantics for the control structures used to model and manage applications within the N1^TM Service Provisioning System software.

A component is a logical grouping of resources (files, directories, database records, etc.) files, that defines an application. The component also includes sequences of instructions used to compare, install, uninstall and control the application. An example of a control is a series of instructions used to “startup” or “shutdown” the application once installed. Possible instructions also include tests for pre and post conditions such as dependency checks on other components and verification that a particular process is running. Finally, the component may declare substitution variables for use within the component itself and any resources it contains as placeholders for values that will be substituted when the plan is run.

A plan is a sequence of instructions typically used to manipulate one or more components. For example, a plan may instruct the provisioning software to install three components and initiate the “startup” control on another. A plan can also be defined as a sequence of other plans, which allows common instruction sequences to be shared between multiple plans.

Types of Plans

The N1 Service Provisioning System software distinguishes between two kinds of plans.

Composite plan (containing only subplans)
Simple plan (collection of simple steps that can't call another subplan)

XML Schema enforces that restriction, so that you can either have a top-level plan with only calls to other subplans, or you can have a simple plan with various simple steps but no calls to other subplans. The distinction is important because the steps contained in a simple plan all execute on the same set of target hosts, whereas the steps of a composite plan may execute on different sets of target hosts, using one set of target hosts for each simple plan recursively contained in the composite plan.

Types of Steps

There are also three kinds of steps that are available with the N1 Service Provisioning System software.

Steps that can be called only from within a component. This category is further divided into steps that can only be called from install blocks, and steps that can only be called from uninstall blocks..
Steps that can be called only from a plan. This category is further divided into steps that can be called only from composite plans, and steps that can be called only from simple plans.
Steps that can be called from either a plan or a component.

Types of Components

Like plans, components come in two varieties, composite and simple. A simple component is a component that contains a single resource, but no references to other components. A composite component is a component that references other components, but does not contain any resources. A composite component may reference both composite and simple components.

A composite component contains the components that it references. The referenced components are referred to as contained components, and the referencing component is referred to as the containing or container component.

A composite component declares whether each of its contained components should be installed as top-level or nested components. If a contained component is installed as top-level, then it can be used by any other component just as if it had been directly installed by a plan. However, if a contained component is installed as nested, then its services are only available to the containing component. Logically, a nested contained component defines a finer-grained unit of functionality required by the containing component, but not otherwise useful to other components. Whereas a top level contained component defines services that will be used by the containing component, but may also be used by other components.

Note –

Composite components contain only references to other components, but not the components themselves. The referenced components are other existing components that are updated and managed independent of the containing component. A component may be referenced by any number of composite components. A component's name is not affected by whether or not it is referenced by other composite component; name conflicts are resolved using paths.

When used within this document, the terms derived component, child component, and parent component refer to component inheritance relationships rather than component composition relationships.

Component References

There are a number of steps that reference components. These steps can be divided into two categories:

Steps that reference components that have yet to be installed:
- Install
Steps that reference components that are already installed:
- Uninstall
- Call
- CheckDependency
- CreateDependency
- AddSnapshot

Steps that reference components that have yet to be installed need only specify the component name and an optional version. However, steps that reference an installed component may additionally specify the install path in which the desired component is located. The installPath is needed in the case of installed component because the same component may be installed multiple times on the same machine.

For example, assume the “apache” component is installed on a host with the following attributes:

Table 1–1 Examples of Component Attributes


Component Instance	Install Path	Version	Install Date
A	/opt	1.3	6/1/01 5:00 PM
B	/usr/local	1.4	6/1/01 6:00 PM
C	/opt	1.2	6/2/01 5:00 PM
D	/usr/local/bin	1.4	6/3/01 5:00 PM
E	/export	1.1	6/4/01 5:00 PM

Table 1–2 shows which installed component is referenced when various combinations of installPath and build version are supplied.

Table 1–2 Component Versions Referenced by Attribute Combination


Install Path	Version	Version Op	Result	Explanation
None	None	None	E	The most recently installed component on the target host is used, regardless of build and installPath.
/opt	None	None	C	The most recently installed component in the named install path is used regardless of build.
/usr/bin	None	None	ERROR	No component is installed in the named path.
None	1.4	=	D	The most recently installed component with the specified build is chosen, regardless of install path.
None	1.5	Any	ERROR	No component is installed with the named build.
/usr/local	1.4	=, >=	B	The component with the install path and build is chosen.
/usr/local	1.2	=	ERROR	No such build at that install path.
/usr/local	1.2	>, >=	B	Path, version and version operator match
/opt	3	Any	ERROR	If two or more components with the same name are installed in the same path, the most recently installed component effectively overwrites any other components installed earlier. Components installed at an earlier date cannot be accessed, even if named directly.

Universal Install Path Format

An install path may be specified within an installed component reference, as described in the previous section. In these cases, the install path attribute specified is converted to universal format prior to resolving the installed component reference. In universal format, all occurrences of the master server's OS specific path separator within the install path are replaced by the “/”, and any trailing “/” is dropped. An exception is made for the root install path (“/”), which is not converted to the empty path.

When the Master Server is running on UNIX based systems, the affect of this conversion is minimal. Install paths that end with “/” will be treated as if no “/” is included. For example, both “/opt/apache/” and “/opt/apache” can be used to refer to the component installed in directory “/opt/apache”.

This conversion takes place because the install path of the installed component is also stored in universal format.

Requirements for Locales and Character Sets

The N1 Service Provisioning System software has been internationalized to install and run in localized environments. You will need to adhere to the following requirements if you want to run the software in a localized environment.

All applications must be run in the same locale or in locales that are equivalent. The Remote Agent, Local Distributors, and CLI Client must run in the same locale as the Master Server.
The software accepts only ASCII characters for file names, directory names, and other input.

Pattern Matching

A number of attributes of elements within a component or plan may contain regular expression patterns. Unless otherwise specified, these patterns are glob-style patterns rather than fully generic regular expressions. This means that '*' is used to match zero or more characters and '?' is used to match exactly one character. Characters listed within brackets ([]) specify a range of possible characters that may match exactly one character.

Variables and Parameter Passing

Both plans and components may declare variables for use by their steps. Component variables are evaluated and bound at the time the component is installed. Therefore, if a step within a component control block references a component-scoped variable, the value used will be the value of that variable at the time the component was installed. Plan variables are evaluated and bound each time the plan is run. Therefore, if a step within a plan references a plan variable, the value used will be the value defined at the time of the plan run, and may vary from one run to another.

A plan may declare both parameters and variables. The value of a variable is defined at the point of declaration based on the values of other variables and constants. A parameter is a special kind of variable whose value is defined by the caller. In the case of a top-level plan, the caller is the user who initiates the plan run. For each parameter declared by the plan, the user enters the desired value for that parameter prior to running the plan. When a plan is invoked as the result of an <execSubplan> call, the plan containing the <execSubplan> call is responsible for explicitly passing values for each of the parameters declared by the called plan.

It is also possible for install, uninstall, snapshot, and control blocks to declare parameters and local variables. As with plans, local variable values are locally defined, and parameter values are defined based on the values passed by the caller of the block. Both may vary each time a plan is run.

There are no facilities for re-assigning the value of a variable or parameter.

Call Compatibility

Component B is said to be call compatible with component A if uses of A can be safely replaced with uses of B in the following cases:

A call to a control block of A.
A call to an uninstall block of A.
A call to a snapshot block of A (using addSnapshot).
A check for dependency on A (using checkDependency or createDependency).
A reference to a variable of A (using config gen :[component:AB:var]).

Call compatibility basically means API/interface compatibility.

Note –

It is often the case that B and A are different versions of components in the same version tree. However, it is also possible for B to be in a distinct version tree if B is an instance of A.

The provisioning software enforces call compatibility for components that serve as system services. Specifically, when a system service is updated to reference a new component, we enforce that the new component is call compatible with the original component. This allows us to ensure that clients of the system service will continue to function properly when the system service is upgraded.

The provisioning software will also optionally verify call compatibility when resolving components referenced by certain installed component targeters. See the "Installed Component Targeters" section for details.

There is no requirement that a component be call compatible with earlier versions of itself, though it is generally recommended whenever possible.

Install Compatibility

Component B is said to be install compatible with component A if B is call compatible with A, and uses of A can be safely replaced with uses of B in the following cases:

A call to an install block of A.
A component extending from A.
A component containing a reference to A.

Install compatibility basically means structural compatibility.

The constraints imposed by install compatibility mean that any existing installed component can be safely replaced by another install compatible component without having to modify our data structures regarding how the original was installed. Call compatibility is a much weaker statement, as the call compatible component may need to be reinstalled over the original component to properly update our data structures.

Note –

For install compatibility to hold, B and A must belong to the same version tree. They may not be components from two distinct version trees.

The provisioning software only enforces install compatibility for components that serve as types. Specifically, when a component type is updated to reference a new version of a component, the new version is install compatible with the original version. Therefore, install compatible updates can be made to component types without having to rebuild and reinstall all existing components derived from that type. As a consequence, if a change is made to a component type that is not install compatible, the client will need to encode that change as a new, distinct component version tree with its own type name. In such cases, the new component type can maintain call compatibility with the original by extending from the original component type. To easily identify the relationship between types, use a versioning system to encode component type names. For example, the component names, EBJ-1.0 and EJB-1.1 easily identifies EJB-1.1 as a later version of the EJB-1.0 component type.

Install compatible implies call compatible, but the reverse does not hold. It also follows that not call compatible implies not install compatible.

Boolean Operators

This section lists elements that serve as boolean operators, and appear within the condition of an <if> step. Boolean operators have the property that they evaluate to true or false.

istrue Boolean Operator

A boolean operator used to determine if a particular value is true. It contains a single attribute "value" and has no child elements. It evaluates to true if and only if the value of the "value" attribute case-insensitive equals "true".

istrue Boolean Operator Attributes

Name	Type	Required	Configurable	Description
value	string	Yes	Yes	The value to compare against "true".

istrue Boolean Operator Examples

Element	Result
<istrue value="True"/>	true
<istrue value="yes"/>	false
<istrue value=":[var]"/>	true if the value of var is true

equals Boolean Operator

A boolean operator used to determine if a particular value is equal to another value. It contains attributes "value1", "value2" and "exact", and has no child elements. It evaluates to true if and only if the values of the "value1" and "value2" attribute are equal. If "exact" is true, then they must be case-sensitive equals, otherwise they must be case-insensitive equals.

Note –

<istrue value="..."/> is a syntactic shorthand for <equals value1="..." value2="true"/>.

equals Boolean Operator Attributes

Name	Type	Required	Configurable	Description
value1	string	Yes	Yes	A value to be compared.
value2	string	Yes	Yes	The other value to be compared.
exact	boolean	No	No	True if a case-sensitive match should be performed, false otherwise. Defaults to false.

equals Boolean Operator Examples

Element	Result
<equals value1="True" value2="true"/>	true
<equals value1="True" value2="true" exact="true"/>	false
<equals value1="apple" value2="apple" exact="true"/>	true
<equals value1="apple" value2="orange"/>	false
<equals value1=":[var1]" value2=":[var2]"/>	true if the value of var1 is equal to the value of var2.

matches Boolean Operator

A boolean operator used to determine if a particular value matches a pattern. It contains attributes "value", "pattern" and "exact", and has no child elements. It evaluates to true if and only if value of the "value" attribute matches the glob-style pattern contained in the value of the "pattern" attribute. If "exact" is true, then they must be case-sensitive match, otherwise they must be case-insensitive match.

matches Boolean Operator Attributes

Name	Type	Required	Configurable	Description
value	string	Yes	Yes	The value to be matched against the pattern.
pattern	string	Yes	Yes	The pattern that should be matched.
exact	boolean	No	No	True if a case-sensitive match should be performed, false otherwise. Defaults to false.

matches Boolean Operator Examples

Element	Result
<matches value="True" pattern="true"/>	true
<matches value="True" pattern="t*"/>	true
<matches value="blue" pattern="*u"/>	false
<matches value="True" pattern="t?ue"/>	true
<matches value="Tue" pattern="t?ue"/>	false
<matches value="True" pattern="t*" exact="true"/>	false
<matches value=":[var1]" pattern=":[var2]"/>	true if the value of var1 matches the pattern of var2.

not Boolean Operator

A boolean operator which negates the result of another boolean operator. It contains no attributes, and a single boolean operator child element. It evaluates to true if and only if the value of its contained operator is not true.

not Boolean Operator Examples

Element

Result

false

true.

and Boolean Operator

A boolean operator which logically ands results of other boolean operators. It contains no attributes. It may contain any number of boolean operator child elements. It evaluates to true if and only if all of its child elements evaluates to true.

and Boolean Operator Examples

Element	Result
<and/>	true
<and><istrue value="True"/></and>	true
<and><equals value1="apple" value2="orange"/></and>	false
<and> <matches value="apple" value2="ap*e"/> <istrue value="TRUE"/> <not><equals value1="apple" value2="orange"/></not></and>	true
<and> <matches value="apple" value2="ap*e"/> <istrue value="TRUE"/> <equals value1="apple" value2="orange"/></and>	false

or Boolean Operator

A boolean operator which logically ors results of other boolean operators. It contains no attributes. It may contain any number of boolean operator child elements. It evaluates to true if and only if it contains at least one child element that evaluates to true.

or Boolean Operator Examples

Element	Result
<or/>	false
<or><istrue value="True"/></or>	true
<or><equals value1="apple" value2="orange"/></or>	false
<or> <matches value="apple" value2="p*e"/> <istrue value="FALSE"/> <equals value1="apple" value2="orange"/></or>	false
<or> <matches value="apple" value2="p*e"/> <not><istrue value="FALSE"/></not> <equals value1="apple" value2="orange"/></or>	true

Attribute Types

entityName Type

Attributes of type entityName have a maximum length of 512 and match the following pattern:

[a-zA-Z_][0-9a-zA-Z-_. ]*

systemName Type

Attributes of type systemName have a maximum length of 64 and match the following pattern:

 [a-zA-Z_][0-9a-zA-Z-_. +]*

identifier Type

Attributes of type identifier have a maximum length of 32 and match the following pattern:

[a-zA-Z_][0-9a-zA-Z_]*

pathName Type

Attributes of type pathName have a maximum length of 512 and match one of the following patterns:

 "/" ( "/" identifier )+

pathReference Type

Attributes of type pathReference have the following syntax:

pathReference: 	
	absolutePath 	
	relativePath  

absolutePath: 
	"/"
	"/" relativePath

relativePath:
	relativePathStart
	relativePathStart "/" relativePath  

relativePathStart:
	".."
	identifier

modifierEnum Type

Attributes of type modifierEnum have either ABSTRACT or FINAL as their value. In general, ABSTRACT indicates that the associated entity must be overridden by a derived component, and FINAL indicates that the associated entity may not be overridden.

accessEnum Type

Attributes of type accessEnum have either PUBLIC, PROTECTED, PATH or PRIVATE as their value. In general, PUBLIC indicates that the accessibility of the associated entity is unlimited, PROTECTED means that accessibility is limited to derived components and entities in the same path, PATH means that accessibility is limited to entities in the same path, and PRIVATE means that accessibility is limited to just the declaring component.

version Type

Attributes of type version match the following pattern:

[0-9]+\.[0-9]+

schemaVersion Type

Attributes of type schemaVersion currently may only have one value:

4.1

Component Change Compatibility

This section enumerates the changes that can be made to a component, and whether they are call and/or install compatible.

Component Attribute Changes

Nature of Change	Install Compatible	Call Compatible
non-final to final	no	yes
final to non-final	yes	yes
non-abstract to abstract	no	yes
abstract to non-abstract	yes	yes
more restrictive access	no	no
less restrictive access	yes	yes
change value of description, label, softwareVendor, or author	no	yes
change value of name or path	no	yes
change from simple to composite component	no	no
change from composite to simple component	no	no

Platform Changes

This section enumerates the changes that can be made to a platform, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
more general platform	yes	yes
more specific platform	no	yes
unrelated platform	no	yes

Here, a platform X is more specific than Y if X is a descendant of Y. It is more general if X is an ancestor of Y.

LimitToHostSet Changes

This section enumerates the changes that can be made to LimitToHostSet, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
any change to limitToHostSet	no	yes

Unlike platforms, the limitToHostSet names a generic, client-specified host set over which there is no explicit control. Its membership can change at any time, so there"s no way to enforce notions of more or less specific host sets.

Extends Changes

This section enumerates the changes that can be made to Extends, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
new base component instance of original	no	yes
original base component instance of new	no	no
new base component unrelated to original	no	no
new base component install compatible with original	yes	yes
new base component call compatible with original	no	yes

Variable Changes

This section enumerates the changes that can be made to a variable, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
add a new variable	no	yes
remove/rename a non-private variable	no	no
remove/rename a private variable	yes	yes
change final var default value	no	yes
change non-final var default value	yes	yes
non-final to final	no	yes
final to non-final	yes	yes
non-abstract to abstract	no	yes
abstract to non-abstract	yes	yes
more restrictive access	no	no
less restrictive access	no	yes

Component Ref List Changes

This section enumerates the changes that can be made to the Component Ref List, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
non-final to final	no	yes
final to non-final	yes	yes
new type instance of original	no	yes
original type instance of new	no	no
new type unrelated to original	no	no
new type install compatible with original	yes	yes
new type call compatible with original	no	yes

Component Ref Changes

This section enumerates the changes that can be made to Component Ref, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
non-final to final	no	yes
final to non-final	yes	yes
non-abstract to abstract	no	yes
abstract to non-abstract	yes	yes
change installMode	no	no
add a new component ref	no	yes
remove/rename a nested component ref	no	no
remove/rename a toplevel component ref	no	no
add/modify/remove nested component argList args	no	yes
add/modify/remove toplevel component argList args	yes	yes
new type instance of original	no	yes
original type instance of new	no	no
new type unrelated to original	no	no
new type install compatible with original	yes	yes
new type call compatible with original	no	yes
new nested comp instance of original	no	yes
original nested comp instance of new	no	no
new nested comp unrelated to original	no	no
new nested comp install compatible with original	yes	yes
new nested comp call compatible with original	no	yes

Resource Changes

This section enumerates the changes that can be made to a resource, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
non-final to final	no	yes
final to non-final	yes	yes
non-abstract to abstract	no	yes
abstract to non-abstract	yes	yes
modify install path, name, group or user	no	yes
modify rsrcName, rsrcVersion	no	yes

Install, Control and Uninstall Block Changes

This section enumerates the changes that can be made to an install, control, or uninstall block, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
non-final to final	no	yes
final to non-final	yes	yes
non-abstract to abstract	no	yes
abstract to non-abstract	yes	yes
more restrictive access	no	no
less restrictive access	no	yes
add a new non-private block	no	yes
add a new private block	yes	yes
remove/rename a non-private block	no	no
remove/rename a private block	yes	yes
change body of block	yes	yes
add/modify/remove local vars of block	yes	yes
add/modify/remove params of private block	yes	yes
add required param to non-private block	no	no
add optional param	yes	yes
remove optional/required param	yes	yes
rename optional param	yes	yes
rename required param of non-private block	no	no
change param from optional to required in non-private block	no	no
change param from required to optional	yes	yes
change param displayMode	yes	yes
change param prompt	yes	yes

Snapshot Block Changes

Snapshot blocks generally have the same compatibility matrix as other blocks listed above, except for dealing with their prepare, capture and cleanup blocks.

Nature of Change	Install Compatible	Call Compatible
add/modify/remove prepare/cleanup block	yes	yes
add/modify/remove capture step	yes	yes

Diff Ignore Changes

This section enumerates the changes that can be made to Diff Ignore, and whether they are call and/or install compatible.

Nature of Change	Install Compatible	Call Compatible
add/modify/remove an ignore directive	yes	yes

The ignore directives are only considered at diff runtime, and do not affect the state of existing snapshots in any way.

Attribute and Child Element Ordering

Within this document, the attributes and child elements that may be used within a particular element are typically documented using tables, one table listing attributes and another listing child elements. The order that the attributes are listed within the tables is not significant; they may appear in any order when used within the associated element. However, unless otherwise noted, the order that child elements are listed within the tables is significant; when used within the associated element, child elements must appear in the same relative order as they appear within the tables.