Chapter 2 The N1 Service Provisioning System Software Component Schema
This chapter describes the XML schema for the N1 Service Provisioning System software components.
For an overview of the provisioning software's XML schema architecture, see Chapter 1, An Overview of N1 Service Provisioning System Software XML Schemas.
Components
In the following tables, the “Config” column indicates whether or not a specific attribute may include substitution variable references in the form “:[varName]”. For details on variable substitution, refer to Chapter 16.
The component Element
The entire component is enclosed by the <component> element. All versions of a component must have the same name and path. Configurable attributes of this element may reference component substitution variables.
component Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
xmlns |
String |
Yes |
No |
Required value: http://www.sun.com/schema/SPS |
|
xmlns:xsi |
String |
Yes |
No |
Required value: http://www.w3.org/2001/ XML Schema-instance |
|
xsi:schema Location |
String |
No |
No |
Recommended value: http://www.sun.com/schema/SPS component.xsd |
|
access |
One of PUBLIC PATH |
No |
No |
The access mode of this component, as described below. Defaults to PUBLIC. |
|
modifier |
modifierEnum |
No |
No |
The modifier of this component, as described below. |
|
name |
entityName |
Yes |
No |
The name of the component |
|
path |
pathName |
No |
No |
The absolute path of the component. If unspecified, the root path “/” is used by default. |
|
description |
String |
No |
No |
The description of the component |
|
label |
String |
No |
No |
A brief description of the component |
|
software Vendor |
String |
No |
No |
The vendor of the software application modeled by this component |
|
author |
String |
No |
No |
The author of this component |
|
version |
schemaVersion |
Yes |
No |
The version of the component schema being used. The only value currently permitted is 4.0. |
|
platform |
String |
No |
No |
The name of the host set containing the hosts that are considered valid physical targets for this component to be installed on, as described below. |
|
limitToHostSet |
String |
No |
No |
The name of the host set containing the hosts that are considered valid targets for this component, as described below. |
|
installPath |
String |
Yes 1 |
Yes |
The path used when this component is installed. For simple components, this value also serves as the root directory in which to install resources. Note: When an instance of this component is installed, the path is stored in universal format. |
1 Only permitted in non-derived components.
component access attribute
The “access" attribute of the <component> element specifies the accessibility of the component, and is limited to values PATH and PUBLIC. It defaults to PUBLIC.
If access is PATH, then the component may only be referenced by other components in the same path as this component. It may not be direct installed by the client and may only be included using a nested reference in other components. If access is PUBLIC, no such restrictions apply.
component modifier attribute
The "modifier" attribute of the <component> element specifies override requirements for the component.
If ABSTRACT, then the component may not be installed. It serves only as a base component for other components to extend. Only abstract components may declare abstract child elements.
If FINAL, then the component may not be extended by another component.
If omitted, then the component may be extended and installed.
component platform attribute
The “platform” attribute of the <component> element specifies the name of the host set containing the hosts that are considered valid physical targets for this component to be installed on. If unspecified, any host that contains an RA residing on a supported platform is considered a to be a valid physical target. Otherwise, the physical targets for any plan that installs this component must be a subset of the hosts contained in the named host set. If the physical targets include a host not contained in the named host set, it is a plan run time error. It is also a plan run time error to specify a name that does not correspond to an existing host set. The plan run time errors described here are reported as preflight errors.
component limitToHostSet attribute
The "limitToHostSet" attribute of the <component> element specifies the name of the host set containing the hosts that are considered valid targets for this plan. If unspecified, all hosts are considered valid targets. Otherwise, the targets specified by the client must be a subset of the hosts contained in the named host set. If the targets include a host not contained in the named host set, it is a plan run time error. It is also a plan run time error to specify a name that does not correspond to an existing host set. The plan run time errors described here are reported as preflight errors.
There are two main differences between the platform and the limitToHostSet attributes. First, the platform names one of the predefined platform host sets, whereas the limitToHostSet names a user-defined host set. Accordingly, if the client wants to limit installation based on a custom host set, they should use "limitToHostSet". Secondly, when a component is targeted at a virtual host, the limitToHostSet is tested against the virtual host, whereas the platform is tested against the root physical host of that virtual host. Accordingly, setting a limitToHostSet but no platform allows a component to be installed on a particular set of virtual hosts that might reside on different physical platforms (as is the case with WebLogic applications). Setting a platform but no limitToHostSet allows a component to be installed on any host that is rooted by a physical host with the given platform. Setting both allows one to constraint both degrees.
component attribute inheritance
Except for installPath and limitToHostSet, component attributes are not inherited.
The installPath attribute is inherited, and may not be overridden by derived components. Note, however, that the base component may use component variables in specifying its value, and the value of these variables may be overridden.
The limitToHostSet attribute is also inherited, and may be overridden by derived components only if the base component did not specify a limitToHostSet. Note that since the limitToHostSet value names a mutable, client managed entity, the relation of host set can not be reasoned about in the same way as platforms.
The platform attribute is not inherited. However, the platform value of a derived component may be no more general than that of the base component. If the platform is unspecified in a derived component, then it also must be unspecified (or specified as “any”) in the base component.
component Child Elements
|
Name |
How Many? |
Description |
|---|---|---|
|
extends |
0 or 1 |
The base component from which this component is derived. |
|
varList |
0 or 1 |
List of substitution variables used by this component and the configuration resources it contains. |
|
resourceRef |
0 or 1 |
Resources managed by this simple component. May not be used with <componentRefList>. |
|
component RefList |
0 or 1 |
List of components referenced by this composite component. May not be used with <resourceRef>. |
|
installList |
0 or 1 1 |
List of install step blocks, each providing a different way to install this component. |
|
uninstallList |
0 or 1 1 |
List of uninstall step blocks, each providing a different way to uninstall this component. |
|
snapshotList |
0 or 1 |
List of snapshot blocks, each providing a different way to capture the installed state of this component. |
|
controlList |
0 or 1 |
List of controls that are available for this component. |
|
diff |
0 or 1 |
List of directives used by the difference engine when running comparisons on components derived from this component. |
1 Required in non-derived components.
The extends Element
The <extends> element is a child of the <component> element and is used to declare base component from which this component is derived. The base component may not be final.
This component will automatically inherit various attributes and elements of the base component. It can selectively override certain aspects of the inherited data. Allowances for inheritance and overrides are specified in the description of the attribute/element in question.
A component is said to be an instance of the component that it extends. It is also an instance of the components that the base component is an instance of.
extends Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
type |
1 |
Specifies the base component. |
The type Element
The <type> element is a child of the <extends>, <componentRefList> and <componentRef> elements and names a base component type.
type Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
systemName |
Yes |
No |
The name of the system type component that serves as the base type. |
The component varList Element
The component <varList> element is a child of the <component> element and is used to declare the list of component-scoped substitution variables used by this component and the configuration resources it contains.
component varList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
var |
1 or more |
A component substitution variable declaration, including name and default value. |
component varList Inheritance and Overriding
By default, a derived component inherits the accessible <varList> element contents of its base component. When a derived component declares a <varList>, its contents are effectively merged with those of the base component. The derived component may declare new <var> elements and override inherited ones, but may not remove elements declared by the base component.
The component var Element
The component <var> element is a child of the component <varList> element and is used to declare a component substitution variable including name and default value.
component var Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
access |
access Enum |
No |
No |
The access mode of the variable, as described below. Default is PUBLIC. |
|
modifier |
modifier Enum |
No |
No |
The modifier of the variable, as described below. |
|
name |
identifier |
Yes |
No |
The name of the substitution variable. The name must be unique among every other substitution variable in the enclosing <varList>. |
|
default |
String |
Yes 1 |
Yes |
The default value of the substitution variable, which may include references to other substitution variables, target host attributes, and installed component variables. |
1 May not be included in abstract variables.
var access Attribute
The "access" attribute of the <var> element specifies the accessibility of the variable.
If PUBLIC, access is not restricted in any way.
If PROTECTED, access is limited to derived components and entities in the same path.
If PATH, access is limited to entities in the same path.
If PRIVATE, access is limited to this component.
var modifier Attribute
The "modifier" attribute of the <var> element specifies the override requirements for the variable.
If ABSTRACT, the variable "default" attribute is omitted and must be specified by non-abstract derived components. Variables may only be declared abstract if the component is also declared abstract. Abstract variables may not be private. Non-abstract variables must declare a default value.
If FINAL, the variable may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the variable.
var Inheritance and Overriding
By default, a derived component inherits all accessible variables of its base component, including access mode, modifier, and default value.
A derived component may define additional variables by using names that are not among the variables inherited from the base component. A derived component may override the default value, modifier, and access mode of a non-final inherited variable by re-declaring a variable with the same name. When a variable is overridden, the entire content of the variable must be re-declared, including default value, access mode, and modifier. The default value is specified if and only if the overriding variable is non-abstract. The access mode may be no more restrictive than the base component mode.
When a variable is overridden, all references to the variable evaluate to the overridden value, including those in the base component.
Note –
If the derived component is declared as non-abstract, then any abstract variables declared by the base component must be overridden by the derived component.
The resourceRef Element
The <resourceRef> element is a child of the <component> element and specifies the resource managed by this component. It may not be used in conjunction with the <componentRefList> element. Configurable attributes of this element and its children may reference component substitution variables.
Note –
Resources have implicit PUBLIC access mode.
A component is considered a simple component if it is derived from a simple component, or is a non-derived component that contains a <resourceRef> element. Derived components may only contain a <resourceRef> element if they are derived from a simple component.
resourceRef Element attributes
|
Name |
Type |
Req, |
Configurable |
Description |
|---|---|---|---|---|
|
modifier |
modifierEnum |
No |
No |
The modifier of the resource, as described below. |
resourceRef modifier Attribute
The "modifier" attribute of the <resourceRef> element specifies the override requirements for the resource.
If ABSTRACT, the resourceRef <resource> element is omitted and must be specified by non-abstract derived components. ResourceRefs may only be declared abstract if the component is also declared abstract. Non-abstract resourceRefs must declare a <resource> element.
If FINAL, the resourceRef may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the resourceRef.
resourceRef Child elements
|
Name |
How Many |
Description |
|---|---|---|
|
installSpec |
1 1 |
Specifies how the resource is to be installed. |
|
resource |
1 2 |
Identifies the associated resource. |
1 Only permitted in non-derived components. 2 May not be included in abstract resources.
resourceRef Inheritance and Overriding
By default, a derived component inherits the <resourceRef> element of its base component.
A derived component may override the modifier and <resource> element of a non-final inherited <resourceRef> element by re-declaring the <resourceRef> element. When a <resourceRef> element is overridden, the <installSpec> element is omitted, as its contents may not be overridden. The <resource> element is specified if and only if the overriding <resourceRef> is non-abstract.
When a <resourceRef> is overridden, then all uses of the resource (including <deployResource> and <addResource>) will resolve to the overridden value, including uses within the base component.
Note –
If the derived component is declared as non-abstract, and the <resourceRef> element of the base component is abstract, then the derived component must override the <resourceRef> element.
The installSpec Element
The <installSpec> element is a child of the <resourceRef> element and is used to specify the way in which the associated resource is to be installed.
This element is inherited by derived components, and may not be overridden. Note, however, that the base component may use component variables in specifying values for <installSpec> attributes, and the values of these variables may be overridden.
installSpec Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
String |
Yes |
Yes |
The name to use for the resource when it is installed. |
|
path |
String |
No |
Yes |
The directory path in which to install the resource. Relative directories are considered relative to the installPath attribute of the containing component. If unspecified, the component installPath attribute is used by default. |
|
permissions |
String |
No |
Yes |
The permissions to assign to this resource when installed, in the format of an octal triplet, as defined by the UNIX chmod command. The first digit represents permissions for the owner of the file, the second is permissions for other users in the file"s group, and the third is permissions for other users. Each digit is the sum of the numbers corresponding to the desired permissions where 1 is execute, 2 is write and 4 is read. So "777" gives everyone read, write and execute permission on the file. If unspecified, the resource is installed with default permissions. |
|
user |
String |
No |
Yes |
The user to assign as the owner of this resource when installed. If unspecified, the user to use is determined by the plan executor. |
|
group |
String |
No |
Yes |
The group to assign to this resource when installed. If unspecified, the group to use is determined by the plan executor. |
|
deploy Mode |
One of: ADD_TO or REPLACE |
No |
Yes |
Specifies the way in which the associated directory resource is deployed. ADD_TO means directory contents will be added to any existing files in the target directory. REPLACE means directory contents will replace all existing files in the target directory. If unspecified, REPLACE is used by default. This attribute is ignored for non-directory resources. |
|
diffDeploy |
Boolean |
No |
Yes |
Specifies whether the resource should be deployed in differential deploy mode. If unspecified, false is used by default. If differential deploy mode is enabled, then only resources which have not previously been deployed will be deployed. |
The resource Element
The <resource> element is a child of the <resourceRef> element and is used to identify the resource to be deployed by this component.
If the referenced resource is a configurable resource, it may contain substitution variable references to any component-scoped variable accessible to the containing component.
resource Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
String |
Yes |
No |
The full path name of a resource managed by the resource manager. |
|
version |
version |
Yes |
No |
The version of the resource managed by the resource manager. |
The componentRefList Element
The <componentRefList> element is a child of the <component> element and specifies the list of components referenced by this component. It may not be used in conjunction with the <resourceRef> element. Configurable attributes of this element and its children may reference component substitution variables.
A component is considered a composite component if it is derived from a composite component, or is a non-derived component that does not contain a <resourceRef> element. Derived components may only contain a <componentRefList> element if they are derived from a composite component.
componentRefList Element attributes
|
Name |
Type |
Req, |
Configurable |
Description |
|---|---|---|---|---|
|
modifier |
FINAL |
No |
No |
The modifier of the list, as described below. |
componentRefList modifier Attribute
The "modifier" attribute of the <componentRefList> element specifies the override requirements for the list. If specified, the value must be FINAL.
If FINAL, derived components may not declare new <componentRef> elements.
If unspecified, then derived components can add new <componentRef> elements.
In either case, derived components may override the <type> element, and non-final inherited <componentRef> elements. If the base component"s componentRefList modifier is final, then that of the derived component must also be final.
Note –
A final modifier on the <componentRefList> element does not imply that each of the contained <componentRef>s are also final.
componentRefList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
type |
0 or 1 |
Specifies the type that all referenced components must be instances of. If unspecified, referenced components may be of any type. |
|
componentRef |
0 or more |
A component reference. |
componentRefList Inheritance and Overriding
By default, a derived component inherits the <componentRefList> element contents of its base component. When a derived component declares a <componentRefList>, its contents are effectively merged with those of the base component. The derived component may declare new <componentRef> elements and override inherited ones, but may not remove elements declared by the base component.
A derived component may override the <type> element declared by the <componentRefList> of the parent component by re-declaring the <type> within its <componentRefList>. In this case, the overridden type must be an instance of the original type, or the original must be unspecified. Furthermore, all referenced components must be instances of the overridden type, including those inherited from the base component.
The componentRef Element
The <componentRef> element is a child of the <componentRefList> element and specifies a component referenced by this component.
Note –
Component refs have implicit PUBLIC access mode.
The componentRef Element attributes
componentRef modifier Attribute
The "modifier" attribute of the <componentRef> element specifies the override requirements for the component reference.
If ABSTRACT, the component reference <component> element is omitted and must be specified by non-abstract derived components. Component references may only be declared abstract if the component is also declared abstract. Non-abstract component references must declare a <component> element.
If FINAL, the component reference may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the component reference.
componentRef installMode Attribute
The installMode attribute of the <componentRef> element specifies the way in which the referenced component should be installed and targeted thereafter. If the referenced component is installed as TOPLEVEL, then it can be used by any other component just as if it had been directly installed by a plan. However, if the referenced component is installed as NESTED, then its installation is implicitly scoped to that of the referencing component, and its services are only available to the referencing component.
Logically, a nested referenced component defines a finer-grained unit of functionality required by the referencing component, but not otherwise useful to other components. Whereas a toplevel referenced component defines services that will be used by the referencing component, but may also be used by other components.
The lifetime of a nested referenced component is implicitly scoped to that of the referencing component. The nested referenced component can only be installed during the installation of the referencing component, and is implicitly uninstalled when the referencing component is uninstalled. In contrast, the lifetime of a toplevel referenced component is not tied to that of the referencing component in any way. The referencing component may install a toplevel referenced component when it is installed, or the referenced component have been installed previously or later by other means. When the referencing component is uninstalled, a toplevel referenced component will remain installed unless it is explicitly uninstalled by the referencing component. Other components are also free to uninstall it.
The componentRef Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
type |
0 or 1 |
Specifies the type that the referenced component must be an instanceof. It must be an instanceof the type specified by the enclosing <componentRefList>. If unspecified, the type specified by the enclosing <componentRefList> is used. |
|
argList |
0 or 1 |
A list of values to be used as component variable settings for the referenced component when it is installed. |
|
component |
1 1 |
The referenced component. |
1 May not be included in abstract componentRefs.
componentRef Inheritance and Overriding
By default, a derived component inherits all component references of its base component.
If the <componentRefList> element of the base component is non-final, the a derived component may define additional component references by using names that are not among those of the component references inherited from the base component.
A derived component may override a component reference of a non-final inherited component reference by redeclaring a component reference with the same name. When a component reference is overridden, the entire content of the component reference must be re-declared. The overriding installMode must be the same as that of the original reference. The overriding <type> element must be an instance of the original type. The overriding <argList> element is merged with the original, as described in the following section. The <component> element is specified if and only if the overriding reference is non-abstract.
When a component reference is overridden, all uses of the component reference evaluate to the overridden value, including those in the base component.
Note –
If the derived component is declared as non-abstract, then any abstract component references declared by the base component must be overridden by the derived component.
The componentRef/argList Element
The <argList> child element of the <componentRef> element specifies a list of values to be used as component variable settings for the referenced component when it is installed. The format of the <argList> is the same as that of the <argList> child element of the <call> step. Each attribute of the <argList> element names a component variable in the referenced component or the declared type, if the reference is ABSTRACT. The value of the <argList> attribute is the override value that should be used for the named component variable when the referenced component is installed.
Note –
When a component reference is overridden by a derived component, the <argList> of the base and derived components are effectively merged by first applying the contents of the <argList> of the base component to the referenced component, and then applying the <argList> of the derived component. When processing the <argList> of the base component reference, only variables defined in the declared type of the base component reference are considered.
Component variables not named in the <argList> will use their default value when installed. If no <argList> is specified, then the referenced component will be installed using default values for all its variables. The variables of the referenced component named in the <argList> must be accessible to the referencing component. Furthermore, they must be declared with access mode PUBLIC or PROTECTED, and may not be FINAL.
Note –
For top-level referenced components, the <argList> element is only used if the referenced component is installed by the referencing component. The referenced component may have been installed by other means, in which case the <argList> has no bearing.
The componentRef/component Element
The <component> child element of the <componentRef> element identifies the referenced component. It has the same structure as the <component> repository component targeter, except that the "host" attribute is not permitted. The referenced component version must exist in the repository at the time the containing component is saved.
Note –
If the "version" attribute is not specified, then the version is resolved to the latest version of the referenced component that exists at the time the containing component is saved. It is a save time error if no versions of the referenced component exist. Once the containing component is saved, the versions of all the components it references are locked, and cannot be modified without creating a new version of the containing component.
The installList Element
The <installList> element is a child of the <component> element and contains one or more named install step blocks, each providing a different way to install this component. Many components will have only one install block as a child of this element.
Multiple install blocks can be used when different steps are required for different installation environments. For example, steps to deploy an EBJ app to a server cluster versus deploy to a single managed server, or steps to install for the first time versus steps to upgrade the application.
installList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
installSteps |
1 or more |
A named install block containing steps that may be executed to install this component. |
installList Inheritance and Overriding
By default, a derived component inherits the accessible <installList> element contents of its base component. When a derived component declares an <installList>, its contents are effectively merged with those of the base component. The derived component may declare new <installSteps> elements and override inherited ones, but may not remove elements declared by the base component.
The installSteps Element
The <installSteps> element is a child of the <installList> element and lists the sequence of steps to be executed in order to install this component. When an <install> step causes this component to be installed, the steps listed here are executed in order. Typically, the install steps steps of a simple component include a <deployResource> step, and the install steps of a composite component include one or more <install> steps to install referenced components.
installSteps Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
access |
accessEnum |
No |
No |
The access mode of the install block, as described later. Default PUBLIC. |
|
modifier |
ModifierEnum |
No |
No |
The modifier of the install block, as described later. |
|
name |
entityName |
Yes |
No |
The name of the install block. The name must be unique among all install blocks in the containing <installList>. |
|
description |
String |
No |
No |
A description of the install block. Useful for documentation purposes. |
installSteps access Attribute
The "access" attribute of the <installSteps> element specifies the accessibility of the install block.
If PUBLIC, access is not restricted in any way.
If PROTECTED, access is limited to derived components and entities in the same path.
If PATH, access is limited to entities in the same path.
If PRIVATE, access is limited to this component.
Note –
Only PUBLIC blocks may be direct run.
installSteps modifier Attribute
The "modifier" attribute of the <installSteps> element specifies the override requirements for the install block.
If ABSTRACT, the block may not include a body. The body must be specified by non-abstract derived components. Install blocks may only be declared abstract if the component is also declared abstract. Abstract blocks may not be private. Non-abstract blocks must declare a body.
If FINAL, the install block may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the block.
installSteps Child elements
The <installSteps> element children consist of an optional <paramList> element followed by the body, where the body consists of an optional local <varList> element followed by zero or more “shared ”, or “component install-only” steps. Note that the body is not included if the install block is declared abstract.
installSteps Inheritance and Overriding
By default, a derived component inherits all accessible install blocks of its base component.
A derived component may define additional install blocks by using names that are not among those of the install blocks inherited from the base component. A derived component may override a non-final inherited install block by redeclaring a block with the same name. Note that blocks are overridden using name alone, and may not be overloaded based on parameters. When a block is overridden, the entire content of the block must be re-declared, including the access mode, modifier, parameters and body. The body is specified if and only if the overriding block is non-abstract. The access mode may be no more restrictive than that of the base component.
The signature of the overriding block in the derived component must be compatible with that of the base component. By compatible, it is meant that any arguments that are acceptable to the base block must also be acceptable to the derived block.
A derived block is compatible with a base block if:
-
It does not declare a new required parameter.
-
It does not redefine a parameter that was optional in the parent block to be required.
The following signature changes are considered compatible:
-
Removal of a parameter (required or optional).
-
Making a required parameter optional.
-
Addition of an optional parameter.
When a block is overridden, then all references to the block evaluate to the overridden value, including those in the base component.
Note –
If the derived component is declared as non-abstract, then any abstract blocks declared by the base component must be overridden by the derived component.
A block in a derived component may explicitly call into a block defined by the base component even if the derived overrides the block using the <superComponent> targeter.
The paramList Element
The <paramList> element is a child of the <installSteps>, <uninstallSteps>, <snapshot> and <control> elements and is used to declare a list of parameters that may be used by the steps of the enclosing element. The value of the parameters are defined by the caller based on the content of the caller's <argList> element. For example, in the case of a <paramList> within an <installSteps> block, parameter values are defined based on the <argList> of the <install> step that invoked the <installSteps> block.
The steps of the enclosing element may use locally-scoped variables declared in the local <varList> element, parameters declared in the <paramList> element, and component-scoped variables declared in the component <varList> element of the enclosing component. If a <paramList> parameter has the same name as a component <varList> variable, the value of the parameter is used. In this case, the parameter is said to “hide” the component variable. Hiding is not permitted between local variables and parameters, as their names must be distinct.
paramList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
param |
1 or more |
A parameter declaration, including name and default value. |
The param Element
The <param> element is a child of the <paramList> element and is used to declare a parameter including name and default value. The default value is used only if the caller does not explicitly pass a value for this parameter. If the default value is unspecified and the caller does not explicitly pass a value for this parameter, a preflight error is raised at plan runtime.
The param element includes optional prompt and displayMode attributes for use when the containing install/uninstall/control block is invoked directly by the client rather than from a plan or another component.
param Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of the parameter. The name must be unique among every other local variable and parameter declared by the enclosing element. |
|
prompt |
String |
No |
No |
The UI text to display when prompting for the value of the parameter. If unspecified, name is used by default. |
|
default |
String |
No |
Yes |
The default value of the parameter, which may include references to component variables, target host attributes, and installed component variables, but not other parameters. |
|
display Mode |
One of: PASSWORD CLEAR BOOLEAN |
No |
No |
The display mode of the parameter. If unspecified, CLEAR is used by default. If PASSWORD, the client-entered value will be hidden (e.g. not shown or replaced with ***). If BOOLEAN, the parameter is entered using a checkbox. Otherwise if CLEAR or BOOLEAN, it is safe for the value to be displayed as entered. |
The local varList Element
The local <varList> element is a child of the <installSteps>, <uninstallSteps>, <snapshot> and <control> elements and is used to declare a list of variables that may be used by the steps of the enclosing element. The values of the variables are defined at the point of declaration, and cannot be redefined.
The steps of the enclosing element may use locally-scoped variables declared in the local <varList> element, parameters declared in the <paramList> element, and component-scoped variables declared in the component <varList> element of the enclosing component. If a local <varList> variable has the same name as a component <varList> variable, the value of the local variable is used. In this case, the local variable is said to “hide” the component variable. Hiding is not permitted between local variables and parameters, as their names must be distinct.
local varList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
var |
1 or more |
A local variable declaration, including name and default value. |
The local var Element
The local <var> element is a child of the local <varList> element and is used to declare a local variable including name and value.
local var Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of the local variable. The name must be unique among every other local variable and parameter declared by the enclosing element. |
|
default |
String |
Yes |
Yes |
The default value of the local variable, which may include references to other local variables declared earlier, parameters, component variables, target host attributes, and installed component variables. |
uninstallList Element
The <uninstallList> element is a child of the <component> element and contains one or more named uninstall step blocks, each providing a different way to uninstall this component. Many components will have only one uninstall block as a child of this element. Multiple uninstall blocks can be used when different steps are required for different installation environments. For example, steps to undeploy an EBJ app from a server cluster versus undeploy from a single managed server. Uninstall blocks often correspond one to one with install blocks, and in such cases, by convention use the same name to indicate the correspondence.
uninstallList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
uninstallSteps |
1 or more |
A named uninstall block containing steps that may be executed to uninstall this component. |
uninstallList Inheritance and Overriding
By default, a derived component inherits the accessible <uninstallList> element contents of its base component. When a derived component declares an <uninstallList>, its contents are effectively merged with those of the base component. The derived component may declare new <uninstallSteps> elements and override inherited ones, but may not remove elements declared by the base component.
The uninstallSteps Element
The <uninstallSteps> element is a child of the <uninstallList> element and lists the sequence of steps to be executed in order to uninstall this component. When an <uninstall> step causes this component to be uninstalled, the steps listed here are executed in order. Typically, the uninstall steps of a simple component include an <undeployResource> step, and the uninstall steps of a component component include one or more <uninstall> steps to uninstall referenced components.
uninstallSteps Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
access |
accessEnum |
No |
No |
The access mode of the uninstall block, as described below. Default PUBLIC. |
|
modifier |
modifierEnum |
No |
No |
The modifier of the uninstall block, as described below. |
|
name |
entityName |
Yes |
No |
The name of the uninstall block. The name must be unique among all uninstall blocks in the containing <uninstallList>. |
|
description |
String |
No |
No |
A description of the uninstall block. Useful for documentation purposes. |
uninstallSteps access Attribute
The "access" attribute of the <uninstallSteps> element specifies the accessibility of the uninstall block.
If PUBLIC, access is not restricted in any way.
If PROTECTED, access is limited to derived components and entities in the same path.
If PATH, access is limited to entities in the same path.
If PRIVATE, access is limited to this component.
Note –
Only PUBLIC blocks may be direct run.
uninstallSteps modifier Attribute
The "modifier" attribute of the <uninstallSteps> element specifies the override requirements for the uninstall block.
If ABSTRACT, the block may not include a body. The body must be specified by non-abstract derived components. Uninstall blocks may only be declared abstract if the component is also declared abstract. Abstract blocks may not be private. Non-abstract blocks must declare a body.
If FINAL, the uninstall block may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the block.
uninstallSteps Child elements
The <uninstallSteps> element children consist of an optional <paramList> element followed by a body, which consists of an optional local <varList> element followed by an optional <dependantCleanup> block followed by zero or more “shared ” or “component uninstall-only” steps. Note that the body is not included if the uninstall block is declared abstract.
uninstallSteps Inheritance and Overriding
By default, a derived component inherits all accessible uninstall blocks of its base component. Semantics for overriding an uninstall block are the same as those for overriding an install block.
The dependantCleanup Block Element
The <dependantCleanup> element is a child of the <uninstallSteps> element, and specifies a set of steps to be executed in order to remove components that currently depend on the calling component. It has no attributes, and may include any number of steps that are permitted within the scope of the containing uninstall block. When included, it causes the check for dependant components to be deferred until after the contents of the block have been executed. If there are still dependant components after the block has been executed, then the uninstall fails and the component remains installed. If there are no dependant components remaining, then the uninstall proceeds with the remaining steps.
Note –
If no <dependantCleanup> block is included in an uninstall block, then the block fails immediately if dependant components exist.
The <dependantCleanup> block is often used in conjunction with the <allDependants> targeter to bulk uninstall dependant components.
The snapshotList Element
The <snapshotList> element is a child of the <component> element and contains one or more named snapshot blocks, each providing a different way to capture the installed state of this component on the target host. Multiple snapshot blocks can be used to capture different aspects of the installed state, which allows for fine-grained differencing of the captured installed state and current state of the component.
snapshotList Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
snapshot |
1 or more |
A named snapshot block that may be executed to capture the installed state of this component. |
snapshotList Inheritance and Overriding
By default, a derived component inherits the accessible <snapshotList> element contents of its base component. When a derived component declares a <snapshotList>, its contents are effectively merged with those of the base component. The derived component may declare new <snapshot> elements and override inherited ones, but may not remove elements declared by the base component.
The snapshot Element
The <snapshot> element is a child of the <snapshotList> element and defines a sequence of steps to be executed in order to capture the installed state this component. When a <createSnapshot> or <addSnapshot> step names this snapshot block, the steps within the <prepare> block are executed in order, then files named with the <capture> block are captured within the capture area of the target machine, and finally steps within the <cleanup> block are executed in order.
A snapshot block is also used to compare the current state of a component against its state at the time of installation. In particular, the <prepare> steps are re-executed at the target machine, then files captured at install time are compared against the current state of the files, and the <cleanup> steps are re-executed.
snapshot Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
entityName |
Yes |
No |
The name of the snapshot block. The name must be unique among all snapshot blocks in the containing <snapshotList>. |
|
description |
String |
No |
No |
A description of the snapshot block. Useful for documentation purposes. |
snapshot access Attribute
The "access" attribute of the <snapshot> element specifies the accessibility of the snapshot block.
If PUBLIC, access is not restricted in any way.
If PROTECTED, access is limited to derived components and entities in the same path.
If PATH, access is limited to entities in the same path.
If PRIVATE, access is limited to this component.
snapshot modifier Attribute
The "modifier" attribute of the <snapshot> element specifies the override requirements for the snapshot block.
If ABSTRACT, the block may not include a body. The body must be specified by non-abstract derived components. Snapshot blocks may only be declared abstract if the component is also declared abstract. Abstract blocks may not be private. Non-abstract blocks must declare a body.
If FINAL, the snapshot block may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the block.
snapshot Child elements
|
Name |
How Many? |
Description |
|---|---|---|
|
paramList |
0 or 1 |
A list of parameters for use within the prepare, capture and cleanup blocks of this snapshot. |
|
varList |
0 or 1 |
A list of local variables for use within the prepare, capture and cleanup blocks of this snapshot. |
|
prepare |
0 or 1 |
Contains steps to be executed in preparation for the file capture or comparison. |
|
capture |
0 or 1 |
Contains a list of files and directories to be captured as part of this snapshot |
|
cleanup |
0 or 1 |
Contains steps to be executed after the capture or comparison has completed. |
Note –
If this snapshot is to be called from a <createSnapshot> step, then it may not declare any required parameters in its <paramList> element.
The varList, prepare, capture and cleanup elements collectively define the body of the snapshot. The body is not included if the snapshot block is declared abstract.
snapshot Inheritance and Overriding
By default, a derived component inherits all accessible snapshot blocks of its base component. Semantics for overriding a snapshot block are the same as those for overriding an install block.
Note –
There is no way to call the base component snapshot block"s prepare block from a derived component snapshot block"s prepare block. Same goes for cleanup. To do this, the base component must factor its prepare/cleanup steps into a control block that may be called by the derived component.
The snapshot prepare Child element
The <prepare> element is a child of the <snapshot> element and defines a sequence of steps to be executed in preparation for the file capture or comparison. Note that these steps are executed both as a result of a <createSnapshot> or <addSnapshot> step that targets this snapshot, and a comparison run that targets this snapshot. In all cases, these steps are executed prior to capturing any files or performing any comparisons.
prepare Child elements
The <prepare> element children consist of one or more <call>, <execNative> and/or <transform> steps. No other steps are permitted. The contained steps may reference local parameters and variables declared by the snapshot block, as well as unhidden component substitution variables.
The snapshot capture Child element
The <capture> element is a child of the <snapshot> element and defines the files and resources that are to be captured as part of this snapshot. Note that the capture occurs only after the steps in the <prepare> block have executed, and that once the capture is complete, the steps in the <cleanup> block will execute.
capture Child elements
The <capture> element children consist of one or more <addFile>, <addSnapshot>, and/or <addResource>, elements. The file and directories listed in this block are captured in the order specified. The contained children may reference local parameters and variables declared by the snapshot block, as well as unhidden component substitution variables.
The capture addFile Child element
The <addFile> element is a child of the <capture> element and denotes a file that is to be captured as part of the containing snapshot.
addFile Element attributes
Note –
Values can be multibyte character strings.
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
path |
String |
Yes |
Yes |
The pathname of a file or directory on the filesystem of the target host. |
|
ownership |
One of: SET_SELF ADD_SELF ADD_TEMP |
No |
No |
The ownership option for the captured file, as described below. |
|
filter |
One of: DIRECTORIES FILES BOTH |
No |
No |
When the pathname refers to a directory, this attribute is used to indicate whether the directory itself, the files it contains, or both should be captured. If unspecified, BOTH is used by default. If the pathname is not a directory, this attribute is ignored and the file is captured directly. |
|
recursive |
Boolean |
No |
No |
When the pathname refers to a directory, this attribute is used to indicate whether subdirectories should be recursively captured using the current filter settings. If unspecified, true is used by default. If the pathname is not a directory, this attribute is ignored and the file is captured directly. |
|
displayName |
String |
No |
Yes |
Text to be included in the display when this snapshot entry is compared against another. |
addFile ownership attribute
The “ownership” attribute of the <addFile> element specifies the ownership option for the captured file. If unspecified, SET_SELF is used by default.
One aspect of the installed state that is captured by the snapshot is file and directory ownership. This is not the same as UNIX permissions; it is more closely tied to the notion of reference counts. Specifically, a file or directory can be captured as being owned by one or more snapshots. If the file owner later changes as a result of another component installation, this can be recognized and reported when the file is compared against its initial state. This facilitates tracking down differences that result from one component unintentionally overwriting files associated with another component. Snapshot ownership information is captured in a repository on the target host known as the owners table.
The values of the ownership attribute have the following semantics:
-
If the ownership value is SET_SELF, then the owners table should be updated so that it contains a single entry for the associated file or directory. That entry lists the executing installed component and snapshot as owners. It also lists the capture area ID of the captured contents of the file or directory.
-
If the ownership value is ADD_SELF, then the installed component and snapshot should be added as additional owners, sharing the existing capture area ID as the previous owners.
-
The ownership value ADD_TEMP is like ADD_SELF except that a new capture is always created and its ID is always used for the new entry rather than sharing the one of the other owners.
The capture addSnapshot Child element
The <addSnapshot> element is a child of the <capture> element and denotes that an external snapshot block should be executed and its contents added to this snapshot.
Using an <addSnapshot> step is semantically equivalent to adding the prepare steps of the called snapshot to the end of the calling snapshot"s prepare block, adding the cleanup steps of the called snapshot to the start of the calling snapshot"s cleanup block, and adding the capture steps of the called snapshot to the calling snapshot"s capture block in place of the <addSnapshot> step. Accordingly, care should be taken that the files referenced by the called and calling snapshot blocks do not conflict.
Any number of <addSnapshot> steps may appear within a <capture> element, and the called snapshot may itself contain any number of <addSnapshot> steps within its <capture> element.
Note –
When files are added to a snapshot indirectly using <addSnapshot> callouts, the topmost component that initiated the snapshot capture is considered the owner of the files, as opposed to the component that contained the <addFile> directive. Similarly, when a diff is performed on a snapshot, only diff ignore directives of the topmost component that initiated the snapshot are considered. Diff ignore directives contained on components visited as a result of <addSnapshot> callouts are not considered.
addSnapshot Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
blockName |
String |
Yes |
No |
The name of the external snapshot block to execute. |
addSnapshot Child elements
|
Name |
How Many? |
Description |
|
argList |
0 or 1 |
A list of arguments to pass to the snapshot block. |
|
installed component targeter |
0 or 1 |
Identifies the component containing the snapshot block. If unspecified, <thisComponent> is used. |
The capture addResource Child element
The <addResource> element is a child of the <capture> element and denotes a resource associated with the component that is to be captured as part of the containing snapshot. This element may only be included in simple components.
This element serves as a syntactic shorthand for an equivalent <addFile> element, as follows:
-
If the associated resource is a directory resource with deployMode ADD_TO, then <addResource> is equivalent to: <addFile path="path of deployed directory" filter="FILES" displayName=" resourceSourcePath"/>
-
If the associated resource is a directory resource with deployMode REPLACE, then <addResource> is equivalent to: <addFile path="path of deployed directory" displayName="resourceSourcePath"/>
-
Otherwise, the associated resource is a file-based resource and <addResource> is equivalent to: <addFile path="path of deployed file" displayName=" resourceSourcePath"/>
The snapshot cleanup Child element
The <cleanup> element is a child of the <snapshot> element and defines a sequence of steps to be executed after a file capture or comparison has completed. Note that these steps are executed both as a result of a <createSnapshot> or <addSnapshot> step that targets this snapshot, and a comparison run that targets this snapshot. In all cases, these steps are executed after capturing all files or performing comparisons. Cleanup blocks are generally used to remove any temporary files created by the prepare block.
The snapshot cleanup Child elements
The <cleanup> element children consist of one or more <call>, <execNative> and/or <transform> steps. No other steps are permitted. The contained steps may reference local parameters and variables declared by the snapshot block, as well as unhidden component substitution variables.
The controlList Element
The <controlList> element is a child of the <component> element and lists the control blocks available for this component.
controlList Child elements
|
Name |
How Many? |
Description |
|
control |
1 or more |
A control block. |
controlList Inheritance and Overriding
By default, a derived component inherits the accessible <controlList> element contents of its base component. When a derived component declares a <controlList>, its contents are effectively merged with those of the base component. The derived component may declare new <control> elements and override inherited ones, but may not remove elements declared by the base component.
The control Element
The <control> element is a child of the <controlList> element and defines a control block available for this component. A control block is a sequence of steps that may be performed once this component has been installed. For example, component for a database application might include control blocks to “startup” or “shutdown” the database. A <call> step can invoke a control block by name, which causes the control block steps to be executed in order.
control Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|
access |
accessEnum |
No |
No |
The access mode of the control block, as described below. Default PUBLIC. |
|
modifier |
modifierEnum |
No |
No |
The modifier of the control block, as described below. |
|
name |
entityName |
Yes |
No |
The name of the control block. This is referenced from a <call> step to execute the control. |
|
description |
String |
No |
No |
The description of the control block. |
control access Attribute
The "access" attribute of the <control> element specifies the accessibility of the control block.
If PUBLIC, access is not restricted in any way.
If PROTECTED, access is limited to derived components and entities in the same path.
If PATH, access is limited to entities in the same path.
If PRIVATE, access is limited to this component.
Note –
Only PUBLIC blocks may be direct run.
control modifier Attribute
The "modifier" attribute of the <control> element specifies the override requirements for the control block.
If ABSTRACT, the block may not include a body. The body must be specified by non-abstract derived components. Control blocks may only be declared abstract if the component is also declared abstract. Abstract blocks may not be private. Non-abstract blocks must declare a body.
If FINAL, the control block may not be overridden by derived components.
If unspecified, then derived components can choose whether or not to override the block.
control Child elements
The <control> element children consist of an optional <paramList> element followed by a body, which consists of an optional local <varList> element followed by zero or more “shared” steps. Note that the body is not included if the control block is declared abstract.
control Inheritance and Overriding
By default, a derived component inherits all accessible control blocks of its base component. Semantics for overriding a control block are the same as those for overriding an install block.
The diff Element
The <diff> element is a child of the <component> element and contains a list of directives used by the difference engine when running comparisons on components derived from this component.
diff Child elements
|
Name |
How Many? |
Description |
|
ignore |
1 or more |
A directory path to ignore during comparison. |
diff Inheritance and Overriding
A derived component automatically inherits all difference ignore directives declared by the base component. It may also declare additional ignore directives in its own <diff> element. Inherited directives may not be removed.
The ignore Element
The <ignore> element is a child of the <diff> element and specifies a filename path pattern to ignore when using this component in a comparison. This element is typically for files and directories created by the application once installed, such as log files. The configurable attributes of this element may reference component substitution variables.
ignore Element attributes
|
Name |
Type |
Required |
Configurable |
Description |
|
path |
String |
Yes |
Yes |
A glob-style pattern matching the filename paths to ignore. For example, “/logs/*.log” |
Installed Component Targeters
This section lists elements that serve to identify a particular installed component as the target of the containing step (for example, control service call). Note that not all targeters can be used with all targeted steps. Each targeter specifies the steps that it may be used with. The following table summarizes the targeters that may be used for the various targeted steps.
|
targeter |
uninstall |
call |
check-Dependency |
create-Dependency |
add-Snapshot |
|---|---|---|---|---|---|
|
installedComponent |
yes |
yes |
yes |
yes |
yes |
|
systemService |
yes |
yes |
yes |
yes |
yes |
|
systemType |
yes |
yes |
yes |
yes |
yes |
|
thisComponent 1 |
yes |
yes |
no |
no |
yes |
|
superComponent 1 |
yes |
yes |
no |
no |
yes |
|
nestedRef 2 |
yes |
yes |
yes |
no |
yes |
|
allNestedRefs 2 |
yes |
yes |
no |
no |
yes |
|
toplevelRef 2 |
yes |
yes |
yes |
yes |
yes |
|
dependee 1 |
yes |
yes |
no |
no |
yes |
|
allDependants 1 |
yes |
yes |
no |
no |
yes |
1 may only be used for steps appearing within components
2 may only be used for steps appearing within composite components
The systemService Installed Component Targeter
The <systemService> element may be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps. It identifies a particular system service component that is assumed to be installed on the current physical host.
Note –
Use of the <systemService> targeter implicitly retargets to the root physical host of the current host. If one needs to target a system service on a different host, a <retarget> step must be used. One cannot otherwise name a new host within the <systemService> targeter.
installedComponent Targeter attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
entityName |
Yes |
No |
The name of the installed component. |
|
path |
pathReference |
No |
No |
The path of the component. If unspecified, the path of the containing entity is assumed. |
|
version |
version |
No |
No |
The version of the installed component. If unspecified, the most recently installed component with any version is used. |
|
versionOp |
One of:" “=” “>=” “>” |
No |
No |
Specifies the operator to use when comparing the version attribute against versions of components installed on the target host. If more than one installed component applies, the most recently installed is used. If unspecified, ">=" is used by default. Ignored if version unspecified. |
|
only Compat |
Boolean |
No |
No |
If true, specifies that only components that are call compatible with the component having the named version should be matched. If true, a component with the named version must exist. If unspecified, “false” is used by default. Ignored if version unspecified. |
|
installPath |
String |
No |
Yes |
The install path of the installed component. If unspecified, the most recently installed component in any path is used. The value is converted to universal format prior to component resolution. |
|
host |
string |
No |
Yes |
The host on which the component is installed. Defaults to the current host. See the <retarget> step host attribute for details. |
systemService Targeter attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
systemName |
Yes |
No |
The name of the system service component. |
The systemType Installed Component Targeter
The <systemType> element may be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps. It identifies a component that is an instance of a particular type that is assumed to be installed on the target host. If more than one installed component matches the specified criteria, the one that was most recently installed is used.
The installedComponent Installed Component Targeter
The <installedComponent> element may be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps. It identifies a particular installed component instance that is assumed to be installed on the target host.
Note –
This targeter matches the named component directly, and cannot be used to match derived instances of the named component. Use the <systemType> targeter to target components derived from a particular type.
systemType Targeter attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
systemName |
Yes |
No |
The name of the system type component. |
|
installPath |
String |
No |
Yes |
The install path of the desired component. The value is converted to universal format prior to component resolution. |
|
host |
string |
No |
Yes |
The host on which the component is installed. Defaults to the current host. See the <retarget> step host attribute for details. |
The thisComponent Installed Component Targeter
The <thisComponent> element may be used as a targeter for the <call>, <uninstall> and <addSnapshot> steps. It specifies that the component containing the step should be used as target of the step. Only steps contained within a component may use this targeter. This element has no attributes.
Note –
If the steps listed do not contain a component targeter element, then <thisComponent> is assumed by default.
The superComponent Installed Component Targeter
The <superComponent> element may be used as a targeter for the <call>, <uninstall> and <addSnapshot> steps. It specifies that the base component of the component containing the step should be used as target of the step. Only steps contained within a derived component may use this targeter. This element has no attributes.
Note –
This targeter will always bind to the base component"s definition of the step in question, even if the derived component overrides it.
The nestedRef Installed Component Targeter
The <nestedRef> element may be used as a targeter for the <checkDependency>, <call>, <uninstall> and <addSnapshot> steps. It identifies a nested component reference declared or inherited by the current composite component. Only steps within composite components may use this targeter.
It is assumed that the named component reference has already been installed by the calling component, and an error is raised otherwise. Note that if the nested component reference was installed on a host other than the current target host, use of the <nestedRef> targeter will implicitly retarget the associated step to that host.
nestedRef Targeter Attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of a nested component reference within this component. |
The allNestedRefs Installed Component Targeter
The <allNestedRefs> element may be used as a targeter for the <call>, <uninstall> and <addSnapshot> steps. It identifies the set of all nested components references declared or inherited by the current composite component. Only steps within composite components may use this targeter.
Note –
This targeter is special in that it may identify any number of components. If it identifies no components, then the step is a no-op. If it identifies more than one component, then the step is semantically expanded as if there is a separate occurrence of the step that using the <nestedRef> targeter for each component identified. The steps are executed serially rather than in parallel, and ordering of the steps varies depending on the step type, as described later. If execution of the step on one of the components causes an error, then the step will not be executed on the remaining matching components.
When used as a targeter for a <call> or <addSnapshot> step, the targeter matches all nested component references that are currently installed by this component, in the order of installation.
When used as a targeter for an <uninstall> step, the targeter matches all nested component references that are currently installed by this component, in the reverse order of installation.
The toplevelRef Installed Component Targeter
The <toplevelRef> element may be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall> and <addSnapshot> steps. It identifies a toplevel component reference declared or inherited by the current composite component. Only steps within composite components may use this targeter.
This targeter is semantically equivalent to the <installedComponent> targeter, except that the "name", "path" and "version" attributes are predefined based on the referenced component.
toplevelRef Targeter Attributes
The dependee Installed Component Targeter
The <dependee> element may be used as a targeter for the <call>, <uninstall> and <addSnapshot> steps. It identifies an installed component that the calling component has a declared dependency on (created via <createDependency>). Only steps within components may use this targeter.
dependee Targeter Attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of a dependency created by this component. |
The allDependants Installed Component Targeter
The <allDependants> element may be used as a targeter for the <call>, <uninstall> and <addSnapshot> steps. It identifies the set of installed components that have a declared dependency on the calling component (created through <createDependency>). Only steps within components may use this targeter.
This targeter functions similarly to the addNestedRefs targeter in that it causes the containing step to be mapped over all matching components. Order of the mapping over the dependant components is unspecified.
allDependants Targeter Attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of a dependency created on this component by other components. |
Repository Component Targeters
This section lists elements that serve to identify a particular component that resides in the master server repository as the target of the containing step (e.g. install). Note that not all targeters can be used with all targeted steps. Each targeter specifies the steps that it may be used with. The following table summarizes the repository targeters that may be used for the various targeted steps.
|
targeter |
install |
|---|---|
|
component 1 |
yes |
|
thisComponent 2 |
yes |
|
superComponent 2 |
yes |
|
nestedRef 3 |
yes |
|
allNestedRefs 3 |
yes |
|
toplevelRef 3 |
yes |
1 may only by used for steps appearing within simple plan 2 may only be used for steps appearing within components 3 may only be used for steps appearing within composite components
The component Repository Component Targeter
The <component> element may be used as a targeter for the <install> step. It identifies a particular component that is assumed to exist in the CR repository. Only steps contained within a simple plan may use this targeter.
component Targeter Attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
entityName |
Yes |
No |
The name of the component. |
|
path |
pathReference |
No |
No |
The path of the component. If unspecified, the path of the containing entity is assumed. |
|
version |
version |
No |
No |
The version of the component. If unspecified, the latest component is used. |
|
host |
string |
No |
Yes |
The host on which the component should be installed. Defaults to the current host. See the <retarget> step host attribute for details. |
The thisComponent Repository Component Targeter
The <thisComponent> element may be used as a targeter for the <install> step. It specifies that the component containing the step should be used as target of the step. Only steps contained within a component may use this targeter. This element has no attributes.
Note –
If the steps listed do not contain a component targeter element, then <thisComponent> is assumed by default.
The superComponent Repository Component Targeter
The <superComponent> element may be used as a targeter for the <install> step. It specifies that the base component of the component containing the step should be used as target of the step. Only steps contained within a derived component may use this targeter. This element has no attributes.
Note –
This targeter will always bind to the base component"s definition of the step in question, even if the derived component overrides it.
The nestedRef Repository Component Targeter
The <nestedRef> element may be used as a targeter for the <install> step. It identifies a nested component reference declared or inherited by the current composite component. Only steps within composite components may use this targeter.
It is assumed that the named component reference has not been previously installed by the calling component, and an error is raised otherwise. Note that if a nested referenced component is to be installed on different host, a <retarget> step must be used. One cannot otherwise name a new host within the <nestedRef> targeter. It is not possible to install a nested component reference on more than one host for a given containing component.
nestedRef Targeter Attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of a nested component reference within this component. |
The allNestedRefs Repository Component Targeter
The <allNestedRefs> element may be used as a targeter for the <install> step. It identifies the set of all nested components references declared or inherited by the current composite component. Only steps within composite components may use this targeter.
Note –
This targeter is special in that it may identify any number of components. If it identifies no components, then the step is a no-op. If it identifies more than one component, then the step is semantically expanded as if there is a separate occurrence of the step that using the <nestedRef> targeter for each component identified. The steps are executed serially rather than in parallel, and ordering of the steps varies depending on the step type, as described later. If execution of the step on one of the components causes an error, then the step will not be executed on the remaining matching components.
When used as a targeter for an <install> step, the targeter matches all nested component references declared in this component, in the order of declaration.
The toplevelRef Repository Component Targeter
The <toplevelRef> element may be used as a targeter for the <install> step. It identifies a toplevel component reference declared or inherited by the current composite component. Only steps within composite components may use this targeter.
This targeter is semantically equivalent to the <component> targeter, except that the "name", "path" and "version" attributes are predefined based on the referenced component. A toplevel component reference may be installed any number of times on any number of hosts.
toplevelRef Targeter Attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of a toplevel component reference within this component. |
|
host |
String |
No |
Yes |
The host on which the referenced component is to be installed. Defaults to the current host. See the <retarget> step host attribute for details. |
Component Install-only Steps
This section lists steps that may only be used within an install block of a component (may be either simple or composite).
createDependency Step
A step used to create a persistent dependency of the current component on another component. When executed, this step first checks for an installed component matching the given criteria, and fails if no such component exists (just as with the <checkDependency> step). If match is found, then a persistent dependency is created between the matching component (the "dependee") and the calling component (the "dependant"). Note that if multiple installed components match the criteria (possible when no install path is specified), then the latest is used as the dependee. The persistent component is created with the name specified in the step. The name must be unique amongst all dependencies created in the install block.
Once created, the persistent dependency remains until the dependant component is uninstalled. Note that if the installation of the dependant component fails in a subsequent step after having created a persistent dependency, then the dependency is removed immediately at the time of failure.
A given component may depend on any number of other components by executing a <createDependency> step for each. It is recommended (but not required) that the createDependency steps appear as the first steps within an install block so that the installation fails prior to doing any real work if the dependencies are not satisfied.
createDependency Step attributes
|
Name |
Type |
Required |
Configurable |
Description |
|---|---|---|---|---|
|
name |
identifier |
Yes |
No |
The name of the dependency to create. Must be unique among all dependencies created by the current component. |
createDependency Step Child elements
|
Name |
How Many? |
Description |
|
installed component targeter |
1 |
Identifies the dependee component. |
createDependency Step Uninstall Implications
A component may not be uninstalled if there exist installed components that depend on it. When an uninstall block of a component is encountered, if there exists one or more persistent dependencies for which the component is the dependee, then the uninstall fails immediately. However, if a component B is being uninstalled by another component A, then dependencies created by A on B will not prevent B from being uninstalled, and will be implicitly removed when B is successfully uninstalled.
The dependee component can specify actions to uninstall its dependants using a <dependantCleanup> block.
createDependency Step Reinstall Implications
A component install is considered a reinstall if there is a pre-existing component in the same version tree that is installed on the same host and install path. A component may be reinstalled if and only if the new component also satisfies all the dependants of the original component. A component can always be reinstalled with the same version component, but can only be reinstalled with a different version if the new version also matches the constraints specified in the <createDependency> step that created the persistent component.
When a simple install block of a component is encountered, we determine if the install will overwrite an existing install. If so, then we find all persistent dependencies for which the existing component is the dependee, and re-verify that the constraints of the dependency are still satisfied with the new component being installed. If any are not satisfied, the install of the new component fails, and the original component remains installed. Otherwise, if and when the new component has successfully completed its install, it becomes the new dependee on all persistent dependencies. Also note that when the install of the new component successfully completes, then the original component is considered uninstalled, and all the persistent dependencies for which it was the dependant are removed. This implies that the new component is responsible for recreating dependencies as needed.
createDependency Step Naming Conventions
By convention, dependencies are named using the convention "xxx2yyy", where xxx in some way indicates the name of the dependant component, and yyy in some way indicates the name of the dependee component. For example, a WebLogic managed server might have a "server2domain" dependency on its admin server, and a "server2cluster" dependency on its containing cluster. This convention facilitates self-documentation of the nature of the dependency relationship, and makes it readable for both the dependee and dependant relationships of a particular component.
createSnapshot Step
A step used to create a snapshot of the current installed state of the component being installed. Any number of <createSnapshot> steps may appear within an install block.
Note –
The named snapshot block may not declare any required parameters, as the createSnapshot step does not support argument passing. Argument passing is not supported because doing so would also require support for argument collection and passing at the time a comparison is later performed on the resulting snapshot.
When a comparison is performed on a composite component, it includes all snapshots created directly by that component, as well as the complete tree of snapshots created by the recursive installation of all nested component references. However, snapshots associated with toplevel component references are not considered, and therefore must be explicitly included in the snapshot of the composite component using the <addSnapshot> capture directive, as appropriate.
Also note that nested components may have some inter-dependencies that make it necessary to defer snapshot capture until all such components are installed. A nested component that deploys a directory and a nested component that deploys a file into that directory is an example of such an inter-dependence. In these cases, it is recommended that the containing component install the nested components using parameter passing or special install blocks that tell the nested component not to take the snapshot during their install, and then have the snapshot block of the containing component include appropriate snapshots of the nested components using the <addSnapshot> directive.
createSnapshot Step attributes
|
Name |
Type |
Required |
Configurable |
Description |
|
blockName |
entityName |
Yes |
No |
The name of the snapshot block to execute within this component. |
install Step
A step used to install a component onto a target host. It causes the steps of the named install block of the targeted component to be executed.
The syntax of this step is as specified for the simple plan <install> step, except that the component targeter may be omitted, in which case <thisComponent> is assumed.
When used within a component, this step is often used to call into another existing install block in the same component. In this case, the component is not considered installed until the outermost install block has completed its execution. Furthermore, the component is only considered installed on the host on which the install step was initially targeted, even if calls to other local install blocks were retargeted to other hosts.
This step can also be used within composite components to install referenced components. The referenced components may be installed on hosts other than that on which the containing component is being installed. Note that if the install of the containing component fails, then any nested referenced components that were successfully installed prior to the failure are implicitly uninstalled without executing an uninstall block. However, any toplevel referenced components that were successfully installed prior to the failure remain installed.
Simple Component Install-only Steps
This section lists steps that may only be used within an install block of a simple component.
deployResource Step
A step used to deploy the resource of the containing component. This step has no attributes or child elements.
Directory type resources whose deployMode is ADD_TO have each of their contained files copied, preserving directory structure and creating new directories as needed. Existing directory structure and content will not be changed (other than copying of resource content). Individual file permissions and ownership are updated as appropriate.
Directory type resources whose deployMode is REPLACE are treated the same as deployMode ADD_TO, except that any preexisting directory is recursively removed prior to deployment.
All other resources are copied, then have their permissions and ownership updated as appropriate. Resources checked in as configurable, will undergo variable substitution prior to being copied. Configurable resources may reference any variable that is accessible to the component in which the resource was declared.
Component Uninstall-only Steps
This section lists steps that may only be used within an uninstall block of a component.
uninstall Step
A step used to uninstall a component from a target host. It causes the steps of the named uninstall block of the targeted component to be executed.
The syntax of this step is as specified for the simple plan <uninstall> step, except that the component targeter may be omitted, in which case <thisComponent> is assumed.
When used within a component, this step is often used to call into another existing uninstall block in the same component. In this case, the component is not considered uninstalled until the outermost uninstall block has completed its execution. Furthermore, the component is only considered uninstalled on the host on which the uninstall step was initially targeted, even if calls to other local uninstall blocks were retargeted to other hosts.
This step can also be used within composite components to uninstall referenced components. Note that when a composite component is uninstalled, all of its nested referenced components are that were not explicitly uninstalled are implicitly uninstalled by the system without running an uninstall block. However, toplevel referenced components that were not explicitly uninstalled remain installed.
Simple Component Uninstall-only Steps
This section lists steps that may only be used within an uninstall block of a simple component.
undeployResource Step
This step has no attributes or child elements. A step used to remove the resource of the containing component.
Directory type resources whose deployMode is ADD_TO will have their files removed, but directories remain. Directory type resources whose deployMode is REPLACE will have the entire directory removed.
All other resources are treated as simple files and removed.
Note –
The resource is removed regardless of whether or not it was originally deployed during the install of this component. In particular, even if this component was installed using an install block that did not contain a <deployResource> step, the <undeployResource> step would still cause the resource to be removed as if it had been originally installed by the component.
- © 2010, Oracle Corporation and/or its affiliates