<component> Element

A component is enclosed within the <component> element. All versions of a component must have the same name and path. This element's attributes can reference component-scoped substitution variables.

The <component> element has the following child elements, which must appear in the order shown. These child elements might have their own child elements, attributes, or both.

• <extends> Element

• <varList> Element

• <targetRef> Element

• <resourceRef> Element

• <componentRefList> Element

• <installList> Element

• <uninstallList> Element

• <snapshotList> Element

• <controlList> Element

• <diff> Element

Attributes for the <component> Element

The <component> element has the following attributes:

• xmlns – A required string that has a value of http://www.sun.com/schema/SPS.

• xmlns:xsi – A required string that has a value of http://www.w3.org/2001/XMLSchema-instance.

• xsi:schemaLocation – An optional string. The recommended value is http://www.sun.com/schema/SPS component.xsd.

• access – An optional attribute that specifies the accessibility of the component. These are the legal values:

  • PATH – The component can only be referenced by other components in the same path as this component. You cannot directly install the component, and it can only be included in other components by using a nested reference.

  • PUBLIC – The component can be referenced by any component and is not bound by the restrictions imposed by PATH access. This is the default value.

• modifier – An optional value of type modifierEnum, which specifies the following override requirements for the component:

  • ABSTRACT – Identifies the component as an abstract component. An abstract component serves only as a base component for other components to extend and cannot be installed. Only an abstract component is permitted to declare abstract child elements.

  • FINAL – Identifies the component as a final component, which means that the component cannot be extended by another component.

  If this attribute is omitted, the component can be extended and installed, which is the default.

• name – A required value of type entityName, which is the name of the component.

• path – An optional value of type pathName, which is the absolute path of the component. If this attribute is omitted, the root path (/) is the default value. The value must name a folder that exists at the time that the component is saved.

• description – An optional string that is a description of the component.

• label – An optional string that is a brief description of the component.

• softwareVendor – An optional string that is the vendor name of the software application that is modeled by the component.

• author – An optional string that is the name of the component's author.

• version – A required value of type schemaVersion, which is the version of the component schema. Currently, the only value permitted is 5.0.

• platform – An optional string that specifies the name of the host set that includes the hosts that are valid physical targets on which this component can be installed.

  If this attribute is omitted, any host that contains a Remote Agent and that is a supported platform is a valid physical target. Otherwise, the physical targets for any plan that installs this component must be a subset of the hosts that are contained in the specified host set. If the physical targets include a host that is not part of the specified host set, the plan issues a runtime error. These plan runtime errors are reported as preflight errors. A component save time error is issued if you specify a name that does not correspond to a supported platform host set. Platform host sets are all prefixed with the system# plug-in name. If a component platform host set is unsupported, a new version of the component cannot be checked in until the platform is changed. Any operation on the existing component version that refers to the unsupported platform host set will fail.

• limitToHostSet – An optional string that specifies the name of the host set that contains the hosts that are valid targets for this plan.

  If this element is omitted, all hosts are valid targets. Otherwise, the specified targets must be a subset of the hosts that are included in the named host set. If the targets include a host that is not part of the specified host set, the plan issues a runtime error. These plan runtime errors are reported as preflight errors. A component save time error occurs when you specify a name that does not correspond to an existing, supported host set. If the specified host set is one that is defined by a plug-in, pluginName must be a prefix to the host set name, such as pluginName#hostSetName.

  These are the two main differences between the platform and the limitToHostSet attributes:

  • platform names one of the predefined platform host sets, whereas limitToHostSet names a user-defined host set. Therefore, if you want to limit installation based on a custom host set, use limitToHostSet.

  • When a component is targeted at a virtual host, limitToHostSet is tested against the virtual host, whereas platform is tested against the root physical host of that virtual host.

  Therefore, if you set limitToHostSet but not platform, a component can be installed on a particular set of virtual hosts that might reside on different physical platforms (as is the case with WebLogic applications). However, if you set platform but not limitToHostSet, a component can be installed on any host that is rooted by a physical host with the given platform. If you set both, you can constrain both degrees.

• installPath – A required string only for nonderived components. This path is used when the component is installed. For simple components, this value also serves as the root directory in which to install resources. The path is stored in universal format when an instance of this component is installed. See Universal Install Path Format.

Except for installPath and limitToHostSet, component attributes are not inherited.

The installPath attribute is inherited and cannot be overridden by derived components. However, the base component can use component variables when specifying its value, and the value of these variables can be overridden.

The limitToHostSet attribute is inherited and can be overridden by derived components only if the base component did not specify limitToHostSet.

Because the limitToHostSet value names a mutable, user-managed entity, the relation of host set cannot be reasoned about in the same way as platforms.

The platform attribute is not inherited. However, the platform value of a derived component can be no more general than that of the base component. If platform is not specified in a derived component, platform cannot be specified (or must be specified as any) in the base component.

<extends> Element

The <extends> element is an optional child of the <component> element. This element is used to declare the base component from which this component is derived. The base component cannot be final. If used, this element can only appear one time.

This component automatically inherits the attributes and elements of the base component. The component can selectively override certain aspects of the inherited data. Allowances for inheritance and overrides are specified in the description of the attribute or element in question.

A component is an instance of the component that it extends. A component is also an instance of the components that the base component is an instance of.

The <extends> element has one child element, <type>, which is required and specifies the base component. The <type> element must be used exactly one time per <component> element.

<type> Element

The <type> element names a base component type. This element is a child of the <extends>, <componentRefList>, and <componentRef> elements.

Attributes for the <type> Element

The <type> element has one required attribute of type systemName, name, which is the name of the system type component that serves as the base type. If the specified type is one that is defined by a plug-in, pluginName must be prefixed to the type name, such as pluginName#typeName.

<varList> Element

The <varList> element is an optional child of the <component> element. This element declares the list of component-scoped substitution variables that are used by this component and by its configuration resources. If used, this element can only appear one time.

The <varList> element has one required child element, <var>, which declares a component substitution variable.

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 can declare new <var> elements and override inherited ones, but a derived component cannot remove elements that are declared by the base component.

<var> Element

The <var> element is a child of the <varlist> element, which is a child of the <component> element. The <var> element declares a component substitution variable. You must specify the name of the variable and a default value for each substitution variable that you want to declare.

By default, a derived component inherits all of the accessible variables from its base component, including access mode, modifier, default value, and prompt. The <var> element can appear one or more times in the <varList> element.

A derived component can define additional variables by using names that are not among the variables that have been inherited from the base component. A derived component can override the prompt, default value, modifier, and access mode of a nonfinal inherited variable by re-declaring a variable with the same name. When a variable is overridden, the entire contents of the variable must be re-declared, including prompt, default value, access mode, and modifier. The default value is specified only if the overriding variable is nonabstract. The access mode can 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.

If the derived component is declared as nonabstract, any abstract variables declared by the base component must be overridden by the derived component.

Attributes for the <var> Element

The <var> element has the following attributes:

• access – An optional value of type accessEnum, which specifies the accessibility of the variable. This attribute can have the following values:

  • PUBLIC – Access is not restricted in any way, which is the default.

  • PROTECTED – Access is limited to derived components and entities that are in the same path.

  • PATH – Access is limited to entities that are in the same path.

  • PRIVATE – Access is limited to this component.

• modifier – An optional value of type modifierEnum, which specifies the override requirements for the variable. This attribute can have the following values:

  • ABSTRACT – The variable default attribute is omitted and must be specified by nonabstract derived components. Variables can only be declared as abstract if the component is also declared as abstract. Abstract variables cannot be private. Nonabstract variables must declare a default value.

  • FINAL – The variable cannot be overridden by derived components.

  If the attribute is omitted, derived components can choose whether to override the variable.

• name – A required value of type identifier, which is the name of the substitution variable. Each variable name declared by <var> elements in the <varList> element must be unique.

• default – A required string for nonabstract variables, which is the default value of the substitution variable. This value can include references to other substitution variables, session variables, target host attributes, and installed component variables. However, an abstract variable cannot define a default value, so this attribute cannot be used for abstract variables.

• prompt – An optional string that is a user-readable description of the variable.

<targetRef> Element

The <targetRef> element is an optional child of the <component> element. This element declares that the component is targetable. A targetable component is one that automatically creates a physical host or a virtual host that is associated with the component when it is installed. If used, this element can appear only one time immediately after the <varList> element. This element can be used by both simple and composite components. However, the <varList> element can only be used in components that are being installed as top-level components.

The <targetRef> element has one optional child element, <agent>, which indicates whether the associated host is a physical host or a virtual host. If the <agent> element is present, the host is a physical host. The element body defines the configuration of the remote agent. If the element is not present, the host is a virtual host, which is the default.

Attributes for the <targetRef> Element

The <targetRef> element has the following attributes:

• hostName – A required value, which is the name of the host to create when you intall this component. The name must be unique at the time of installation and must be a valid host name. This value can include component-scoped substitution variable references.

• typeName – An optional value of type systemName, which is the name of the host type to use for the associated host. The specified type must exist at the time that the component is saved. If this host type is defined by a plug-in, the name should include pluginName as a prefix, such as pluginName#typeName.

  If this attribute is omitted, the value is system#crhost.

<agent> Element

The <agent> element is a child of the <targetRef> element. This element indicates that the associated host is a physical host. This element is optional and can be used only one time.

If this element is omitted, the associated host is created as a virtual host. If this element is used, the associated host is created as a physical host, and the <agent> element specifies the configuration of the associated remote agent.

This element is inherited by derived components. A derived component can declare a local <targetRef> element only if the base component did not. This means that a derived component cannot override an inherited <targetRef> element.

Attributes for the <agent> Element

The <agent> element has the following attributes. These attributes can reference component-scoped substitution variables.

• connection – A required value that specifies the connection type that is used to connect to the remote agent. This attribute can have one of the following values:

  • RAW

  • SSL

  • SSH

• ipAddr – A required value that is the IP address of the physical host. This value can be either a server name or an IP address. Server names must be resolvable to an IP address by the master server.

• port – An optional value that is the port on which the remote agent is listening. If connection is RAW or SSL, the default value of port is 1131. If connection is SSH, this attribute is ignored.

• params – An optional value that is at least one parameter that is used to connect to the remote agent.

<resourceRef> Element

The <resourceRef> element is an optional child of the <component> element. This element specifies the resource that is managed by the component. This element can only be used by a simple component. This element cannot be used in conjunction with the <componentRefList> element, which can only be used by composite components. The configurable attributes of this element and its children can reference component substitution variables. Resources have implicit PUBLIC access mode. If used, this element can only appear one time.

A component is a simple component if it is derived from a simple component or if it is a nonderived component that contains a <resourceRef> element. A derived component can only contain a <resourceRef> element if it is derived from a simple component.

The <resourceRef> element has child elements, which must appear in the following order:

• <installSpec> – A required element for nonderived components that specifies how the resource is to be installed. This element cannot be included in derived components.

• <resource> – A required element for nonabstract components that identifies the associated resource. This element cannot be included in abstract components.

By default, a derived component inherits the <resourceRef> element of its base component.

A derived component can override the modifier and the <resource> element of a nonfinal inherited <resourceRef> element by re-declaring the <resourceRef> element. When a <resourceRef> element is overridden, the <installSpec> element is omitted, as its contents cannot be overridden. The <resource> element is specified only if the overriding <resourceRef> is nonabstract.

When a <resourceRef> is overridden, all uses of the resource (including <deployResource> and <addResource>) resolve to the overridden value, including uses in the base component.

If the derived component is declared as nonabstract and the <resourceRef> element of the base component is abstract, the derived component must override the <resourceRef> element.

Attributes for the <resourceRef> Element

The <resourceRef> element has one optional attribute, modifier, which has a value of type modifierEnum. The modifier attribute specifies the following override requirements for the resource:

• ABSTRACT – The <resource> element of <resourceRef> is omitted and must be specified by nonabstract derived components. A <resourceRef> can only be declared abstract if the component is also declared abstract. A nonabstract <resourceRef> must declare a <resource> element.

• FINAL – <resourceRef> cannot be overridden by derived components.

If this attribute is omitted, derived components can choose whether to override the <resourceRef>.

<installSpec> Element

The <installSpec> element is a child of the <resourceRef> element. This element specifies the way in which the associated resource is to be installed. This element is inherited by derived components and cannot be overridden. However, the base component can use component variables to specify values for <installSpec> attributes. The values of these variables can also be overridden.

Attributes for the <installSpec> Element

The <installSpec> element has the following attributes. These attributes can reference component-scoped substitution variables.

• name – A required string that is the name to use for the resource when it is installed.

• path – An optional string that is the path in which to install the resource. Relative directories are considered relative to the installPath attribute of the containing component. If this argument is omitted, the component's installPath attribute is used by default.

• permissions – An optional string that indicates the permissions to assign to the resource when installed.

  The string is in the format of an octal triplet, as defined by the UNIX chmod command. See the chmod(1M) man page. If this attribute is omitted, the resource is installed with default permissions.

• user – An optional string that is the owner of this resource when it is installed. If this attribute is omitted, the user is determined by the plan executor.

• group – An optional string that is the group to assign to this resource when it is installed. If this attribute is omitted, the group is determined by the plan executor.

• deployMode – An optional attribute that specifies the way in which the associated directory resource is deployed. This attribute is ignored if the resource is not a directory.

  • ADD_TO – The directory contents are added to any existing files in the target directory.

  • REPLACE – The directory contents replace all existing files in the target directory.

  If this argument is omitted, the default value, REPLACE, is used.

• diffDeploy – An optional value of type boolean, which specifies whether the resource should be deployed in differential deploy mode. If this attribute is omitted, differential deploy mode is disabled. If differential deploy mode is enabled, only resources that have not previously been deployed are deployed.

<resource> Element

The <resource> element is a child of the <resourceRef> element. This element identifies the resource to be deployed by the component.

If the referenced resource is a configurable resource, it can contain substitution variable references to any component-scoped variable that is accessible to the containing component.

Attributes for the <resource> Element

The <resource> element has the following attributes:

• name – A required string that is the full path name of a resource contained in a checked-in component.

• version – A required value of type version, which is the version of the resource that has been created by an earlier component check-in.

<componentRefList> Element

The <componentRefList> element is an optional child of the <component> element. This element specifies the list of components that are referenced by the component. This element cannot be used in conjunction with the <resourceRef> element. Configurable attributes of this element and its children can reference component substitution variables. If used, this element can only appear one time.

A component is a composite component if it is derived from a composite component or if it is a nonderived component that does not contain a <resourceRef> element. A derived component can only contain a <componentRefList> element if it is derived from a composite component.

The <componentRefList> element has the following optional child elements:

• <type> – Specifies the type that all referenced components must be instances of. If this element is omitted, referenced components can be of any type.

  This element is optional. If used, this element can appear only one time per <componentRefList> element.

• <componentRef> – A reference to a component. This element is optional. If used, this element can appear more than once.

By default, a derived component inherits the contents of the <componentRefList> element from its base component. When a derived component declares a <componentRefList>, its contents are effectively merged with those of the base component. The derived component can declare new <componentRef> elements and override inherited ones. However, the derived component cannot remove elements that are declared by the base component.

A derived component can override the <type> element that is declared by the <componentRefList> element of the parent component. This override is achieved by re-declaring the <type> in its <componentRefList>. In this case, the overridden type must be an instance of the original type or the original must not be specified. Furthermore, all referenced components must be instances of the overridden type, including those that are inherited from the base component.

Attributes for the <componentRefList> Element

The <componentRefList> element has one optional attribute, modifier, which specifies the override requirements of the resource. If this attribute is specified, the value must be FINAL, which means that derived components cannot declare new <componentRef> elements.

If this attribute is omitted, derived components can add new <componentRef> elements. In either case, derived components can override the <type> element and nonfinal inherited <componentRef> elements. If the base component's <componentRefList> modifier attribute is FINAL, the modifier attribute of the derived component must also be FINAL.

When modifier is FINAL for the <componentRefList> element, the modifier attribute of each contained <componentRef> is not necessarily FINAL.

<componentRef> Element

The <componentRef> element is a child of the <componentRefList> element. This element specifies a component that is referenced by this component. This element implies PUBLIC access.

The <componentRef> element has child elements, which must appear in the following order:

• <type> – Specifies the component type the referenced component must be an instance of. It must be an instance of the component type that is specified by the enclosing <componentRefList>.

  This element is optional. If used, this element can appear only one time per <componentRef> element.

  If this element is omitted, the component type specified by the enclosing <componentRefList> is used.

• <argList> – An optional element that is a list of values to be used as component variable settings for the referenced component when it is installed.

  If used, this element can appear only one time as a child of the <componentRef> element.

• <component> – A required element that specifies the referenced component. You cannot use this element in abstract <componentRef> elements.

By default, a derived component inherits all the component references of its base component.

If the <componentRefList> element of the base component is nonfinal, a derived component can define additional component references by using names that are not among those of the component references that are inherited from the base component.

A derived component can override a component reference of a nonfinal inherited component reference by re-declaring a component reference that has the same name. When a component reference is overridden, the entire contents 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. See <argList> Element. The <component> element is specified only if the overriding reference is nonabstract.

When a component reference is overridden, all uses of the component reference evaluate to the overridden value, including those in the base component.

If the derived component is declared as nonabstract, any abstract component references that are declared by the base component must be overridden by the derived component.

Attributes for the <componentRef> Element

The <componentRef> element has the following attributes:

• modifier – An optional attribute of type modifierEnum that specifies the override requirements of the component reference. This attribute has the following values:

  • ABSTRACT – The <component> child element of the <componentRef> element is omitted and must be specified by nonabstract derived components. A <componentRef> can only be declared abstract if the component is also declared abstract. A nonabstract <componentRef> must declare a <component> element.

  • FINAL – The <componentRef> cannot be overridden by derived components.

  If this attribute is omitted, derived components can choose whether to override the component reference.

• name – A required attribute of type identifier that specifies a local name for the referenced component. This name must be unique among all sibling <componentRef> elements.

• installMode – An optional attribute that specifies the way in which the referenced component should be installed and targeted thereafter. If this attribute is omitted, the value is NESTED.

  This attribute has the following values:

  • TOPLEVEL – If the referenced component is installed in this way, it can be used by any other component just as if it had been directly installed by a plan.

  • NESTED – If the referenced component is installed in this way, its installation is implicitly scoped to that of the referencing component. Its services are only available to the referencing component.

  A nested referenced component logically defines a finer-grained unit of functionality that is required by the referencing component. This functionality is not otherwise useful to other components. A top-level referenced component defines services that are used by the referencing component, but can 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 top-level referenced component is not tied to that of the referencing component. The referencing component can install a top-level referenced component when it is installed, or by other means if the top-level referenced component is already installed. When the referencing component is uninstalled, a top-level referenced component remains installed unless it is explicitly uninstalled by the referencing component. Other components are also permitted to uninstall the referencing component.

  To refer to a component that defines a <targetRef> element, a TOPLEVEL <componentRef> must be used. A NESTED <componentRef> cannot be used.

<argList> Element

This <argList> element is a child of the <componentRef> element. This element specifies a list of values to be used as component variable settings for the referenced component when it is installed. The format of this <argList> is the same as that of the <argList> child element of the <call> step. See <call> Step.

If the reference is ABSTRACT, each attribute of the <argList> element names a component variable in the referenced component or the declared type. The value of the attribute for the <argList> element is the override value that should be used for the named component variable when the referenced component is installed.

When a component reference is overridden by a derived component, the <argList> element of the base and derived components are effectively merged. This merge is accomplished by applying the contents of the <argList> of the base component to the referenced component, then applying the <argList> of the derived component. When processing the <argList> of the base component reference, only variables that are defined in the declared type of the base component reference are considered.

Component variables that are not named in the <argList> use their default value when installed. If no <argList> is specified, the referenced component is installed and uses default values for all its variables. The variables of the referenced component named in the <argList> must be accessible to the referencing component. Furthermore, the variables must be declared with the PUBLIC or PROTECTED access mode, and cannot be FINAL.

For top-level referenced components, the <argList> element is only used if the referenced component is installed by the referencing component. The referenced component could have been installed by other means, in which case the <argList> has no bearing.

<component> Element

This <component> element is child of the <componentRef> element. This element identifies the referenced component. This element 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 that the containing component is saved.

If the version attribute is not specified, the version is resolved to be the latest version of the referenced component that exists at the time that the containing component is saved. A save-time error occurs if no versions of the referenced component exist. After the containing component is saved, the versions of all the components it references are locked. The referenced components cannot be modified without creating a new version of the container component.

<installList> Element

The <installList> element is a child of the <component> element. This element contains one or more named blocks of install steps. Each block provides a different way to install the component. Many components have only one install block as a child of the <installSteps> element, described later in this section.

This element is required for nonderived components and optional for derived components. If used, this element can only appear one time.

You can use more than one install block when different steps are required for different installation environments. For example, you might create one install block to deploy an EJB application to a server cluster, another to deploy to a single managed server, another for initial install, and one to upgrade the application.

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 can declare new <installSteps> elements and override inherited ones, but it cannot remove elements that are declared by the base component.

The <installList> element has one child element, <installSteps>, which lists the sequence of steps to be executed to install the component. The <installSteps> element can appear one or more times.

<installSteps> Element

The <installList> element has one child element, <installSteps>, which lists the sequence of steps to be executed to install the component. When an <install> step causes this component to be installed, the steps listed here are executed in order. Typically, the install steps of a simple component include a <deployResource> step. The install steps of a composite component include one or more <install> steps to install referenced components.

The <installSteps> element children consist of an optional <paramList> element followed by the body, which consists of an optional local <varList> element. The local <varList> element is followed by zero or more “shared” or “component install-only” steps. The body is not included if the install block is declared abstract.

By default, a derived component inherits all accessible install blocks of its base component.

A derived component is permitted to define additional install blocks by using names that are not among those of the install blocks inherited from the base component. A derived component can override a nonfinal inherited install block by re-declaring a block with the same name. Blocks are overridden by using name alone, and they cannot be overloaded based on parameters. When a block is overridden, the entire contents of the block must be re-declared, including the access mode, modifier, and parameters. The body is specified only if the overriding block is nonabstract. The access mode can 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. That is, 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 when it does not declare a new required parameter and does not redefine a parameter to be required if that parameter is optional in the parent block.

The following signature changes are compatible:

• Removing a required or optional parameter

• Making a required parameter optional

• Adding an optional parameter

When a block is overridden, all references to the block evaluate to the overridden value, including those in the base component.

If the derived component is declared as nonabstract, any abstract blocks declared by the base component must be overridden by the derived component.

A block in a derived component is permitted to explicitly call into a block that is defined by the base component even if the derived component overrides the block that uses the <superComponent> targeter.

Attributes for the <installSteps> Element

The <installSteps> element has the following attributes:

• access – An optional attribute of type accessEnum, which specifies the accessibility of the install block. The following values are permitted:

  • PUBLIC – Access is unrestricted and is the default access mode.

  • PROTECTED – Access is limited to derived components and entities that are in the same path.

  • PATH – Access is limited to entities that are in the same path.

  • PRIVATE – Access is limited to this component.

  Only PUBLIC blocks can be run directly from the component.

• modifier – An optional attribute of type ModifierEnum, which specifies the override requirements for the install block. The following values are permitted:

  • ABSTRACT – The block cannot include a body. The body must be specified by nonabstract derived components. Install blocks can only be declared abstract if the component is also declared abstract. Abstract blocks cannot be private. Nonabstract blocks must declare a body.

  • FINAL – The install block cannot be overridden by derived components.

  If the modifier attribute is omitted, derived components can choose whether to override the block.

• name – A required attribute of type entityName, which is the name of the install block. The name must be unique among all install blocks in the containing <installList>.

• description – An optional attribute that is a string that describes the install block. This attribute is useful for documentation purposes.

<paramList> Element

The <paramList> element is a child of the <installSteps>, <uninstallSteps>, <snapshot>, and <control> elements. This element declares a list of parameters that can be used by the steps of the enclosing element. The value of the parameters are defined by the caller based on the contents 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 can use the following variables and parameters:

• Locally scoped variables that are declared in the local <varList> element

• Parameters that are declared in the <paramList> element

• Component-scoped variables that are 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 because their names must be distinct.

The <paramList> element has one child, <param>, which is required. This child element is a parameter declaration, which includes a name and a default value. Specify one <param> element for each parameter that you want to define.

<param> ELEMENT

The <param> element is a child of the <paramList> element. This element declares a parameter, which includes a name and a default value. The default value is only used 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 occurs at plan runtime.

ATTRIBUTES FOR THE <param> ELEMENT

The <param> element includes the following attributes. Use the prompt and displayMode attributes when the containing install, uninstall, or control block is invoked directly by the user rather than from a plan or another component.

• name – A required attribute of type identifier that is the name of the parameter. The name must be unique among every other local variable and parameter that is declared by the enclosing element.

• prompt – An optional attribute that is a string that specifies the text to display in the user interface when prompting for the parameter value. If this attribute is omitted, the value of name is used.

• default – An optional attribute that is a string that specifies the default value of the parameter. The parameter can include references to component variables, target host attributes, session variables, and installed component variables, but not to other parameters.

• displayMode – An optional attribute that specifies the display mode of the parameter. The legal values are as follows:

  • PASSWORD – The user-specified value is hidden, which means that the password is not shown or is replaced by asterisks.

  • BOOLEAN – The parameter is specified by means of a check box.

  • CLEAR – The value is displayed as entered.

If the value is CLEAR or BOOLEAN, it can be safely displayed as entered. If the attribute is omitted, the value is CLEAR.

Local <varList> Element

The local <varList> element is a child of the <installSteps>, <uninstallSteps>, <snapshot>, and <control> elements. This element declares a list of variables that can be used by the steps of the enclosing element. The values of the variables are defined at the point of declaration. They cannot be redefined.

The steps of the enclosing element can use the following variables and parameters:

• Locally scoped variables that are declared in the local <varList> element

• Parameters that are declared in the <paramList> element

• Component-scoped variables that are 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 because their names must be distinct.

The local <varList> element has one required child element, <var>, which is a local variable declaration that includes a name and a default value. You can specify more than one <var> element.

LOCAL <var> ELEMENT

The local <var> element is a required child of the local <varList> element and is used to declare a local variable name and its value.

ATTRIBUTES FOR THE LOCAL <var> ELEMENT

The local <var> element has the following attributes:

• name – A required attribute of type identifier, which specifies the name of the local variable. The name must be unique among every other local variable and parameter declared by the enclosing element.

• default – A required attribute of type String, which is the default value of the local variable. This local variable can include the following references:

  • Other local variables that were declared earlier

  • Parameters

  • Component variables

  • Target host attributes

  • Session variables

  • Installed component variables

<uninstallList> Element

The <uninstallList> element is a child of the <component> element. This element contains one or more named <uninstall> step blocks, each of which provides a different way to uninstall the component. Many components have only one uninstall block as a child of this element. You can use more than one uninstall block when different steps are required for different installation environments.

For example, you might create one uninstall block to undeploy an EJB application to a server cluster and another to undeploy to 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.

This element is required for nonderived components and optional for derived components. If used, this element can only appear one time.

The <uninstallList> element has a required child element, <uninstallSteps>. This child element is a named uninstall block that contains steps that can be executed to uninstall the component. Specify one <uninstallSteps> element for each way that you want to uninstall the component.

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 can declare new <uninstallSteps> elements and override inherited ones, but it cannot remove elements that are declared by the base component.

<uninstallSteps> Element

The <uninstallSteps> element is a child of the <uninstallList> element. This element lists the sequence of steps to be executed to uninstall the component. When an <uninstall> step causes this component to be uninstalled, the steps listed in this element are executed in order. The <uninstallSteps> element of a simple component is permitted to include an <undeployResource> step, though it is not required. The <uninstallSteps> element of a composite component is permitted include one or more <uninstall> steps to uninstall the referenced components, though these steps are not required.

The <uninstallSteps> element children consist of an optional <paramList> element followed by a body. The body consists of an optional local <varList> element that is followed by an optional <dependantCleanup> block, which is followed by zero or more “shared” or “component uninstall-only” steps. The body is not included if the uninstall block is declared abstract.

The following example shows the contents of a sample <uninstallSteps> element. Everything after </paramList> defines the body.

<uninstallSteps name="default">
  <paramList>
     <param name="param1"/>
   </paramList>
  <varList>
    <var name="var1" default="my var 1"/>
  </varList>
  <dependantCleanup>
    <uninstall blockName="default">
        <allDependants name="child2parent"/>
    </unisntall>
  </dependantCleanup>
  <undeployResource/>
</uninstallSteps>

By default, a derived component inherits all of the accessible uninstall blocks of its base component. Semantics for overriding an uninstall block are the same as those for overriding an install block.

Attributes for the <uninstallSteps> Element

The <uninstallSteps> element has the following attributes:

• access – An optional attribute of type accessEnum, which specifies the accessibility of the uninstall block. The following values are permitted:

  • PUBLIC – Access is unrestricted, which is the default.

  • PROTECTED – Access is limited to derived components and entities that are in the same path.

  • PATH – Access is limited to entities that are in the same path.

  • PRIVATE – Access is limited to this component.

  Only PUBLIC blocks can be run directly from the component.

• modifier – An optional attribute of type modifierEnum, which specifies the override requirements for the uninstall block. The following values are permitted:

  • ABSTRACT – The block cannot include a body because it must be specified by nonabstract derived components. Uninstall blocks can only be declared abstract if the component is also declared abstract. Abstract blocks cannot be private. Nonabstract blocks must declare a body.

  • FINAL – The uninstall block cannot be overridden by derived components.

  If this attribute is omitted, derived components can choose whether to override the block.

• name – A required attribute of type entityName, which is the name of the uninstall block. The name must be unique among all uninstall blocks in the containing <uninstallList>.

• description – An optional attribute, which is a string that describes the uninstall block. This attribute is useful for documentation purposes.

<dependantCleanup> Element

The <dependantCleanup> element is a child of the <uninstallSteps> element. The <dependantCleanup> element specifies a set of steps to be executed to remove components that currently depend on the calling component. This element has no attributes and can include any number of steps that are permitted within the scope of the containing uninstall block.

When included, this element causes the check for dependent components to be deferred until after the contents of the block have been executed. If dependent components still remain after the block has been executed, the uninstall fails and the component remains installed. If no dependent components remain, the uninstall proceeds with the remaining steps.

If the containing component is targetable, the block can be used to remove components that are installed on its associated component targeting host. If installed components remain on the associated host after this block completes, the uninstall fails.

If a <dependantCleanup> block is not included in an uninstall block, the block fails immediately if dependent components exist.

The <dependantCleanup> block is often used in conjunction with the <allDependants> targeter to uninstall all dependent components at one time.

<snapshotList> Element

The <snapshotList> element is an optional child of the <component> element. This element contains one or more named snapshot blocks. Each snapshot block provides a different way to capture the installed state of this component on the target host. One or more snapshot blocks can be used to capture different aspects of the installed state. This results in a fine-grained comparison of the captured installed state and the current state of the component. If used, this element can only appear one time.

This element has one required child element, <snapshot>, which is a named snapshot block that can be executed to capture the installed state of this component. You can use more than one <snapshot> element.

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 can declare new <snapshot> elements and override inherited ones, but it cannot remove elements declared by the base component.

<snapshot> Element

The <snapshot> element is a child of the <snapshotList> element. This element defines a sequence of steps to be executed 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 server. 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 on the target server. Then, files captured at install time are compared to the current state of the files, and the cleanup steps are re-executed.

The <snapshot> element has the following child elements:

• <paramList> – An optional element that is a list of parameters to be used by the prepare, capture, and cleanup blocks of this snapshot. This element can only appear one time.

• <varList> – An optional element that is a list of local variables to be used by the prepare, capture, and cleanup blocks of this snapshot. This element can only appear one time.

• <prepare> – An optional element that contains steps to be executed in preparation for the file capture or comparison. This element can only appear one time.

• <capture> – An optional element that contains a list of files and directories to be captured as part of this snapshot. This element can only appear one time.

• <cleanup> – An optional element that contains steps to be executed after the capture or comparison has completed. This element can only appear one time.

If this snapshot is to be called from a <createSnapshot> step, it cannot 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.

By default, a derived component inherits all of the accessible snapshot blocks of its base component. Semantics for overriding a snapshot block are the same as those for overriding an install block.

You cannot call the base component snapshot block's prepare block from a derived component snapshot block's prepare block. This restriction applies to cleanup, as well. To make this sort of call, the base component must factor its <prepare> and <cleanup> steps into a control block that can be called by the derived component.

Attributes for the <snapshot> Element

This element has the following attributes:

• access – An optional attribute of type accessEnum, which specifies the accessibility of the snapshot block. The following values are permitted:

  • PUBLIC – Access is unrestricted, which is the default.

  • PROTECTED – Access is limited to derived components and entities that are in the same path.

  • PATH – Access is limited to entities that are in the same path.

  • PRIVATE – Access is limited to this component.

• modifier – An optional attribute of type modifierEnum, which specifies the override requirements for the snapshot block. The following values are permitted:

  • ABSTRACT – The block cannot include a body because it must be specified by nonabstract derived components. Snapshot blocks can only be declared abstract if the component is also declared abstract. Abstract blocks cannot be private. Nonabstract blocks must declare a body.

  • FINAL – The snapshot block cannot be overridden by derived components.

  If this attribute is omitted, derived components can choose whether to override the block.

• name – A required attribute of type entityName, which is the name of the snapshot block. The name must be unique among all snapshot blocks in the containing <snapshotList>.

• description – An optional attribute that is a string that describes the snapshot block. This attribute is useful for documentation purposes.

<prepare> Element

The <prepare> element is a child of the <snapshot> element. This element defines a sequence of steps to prepare to capture or compare files. 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.

The <prepare> element children consist of one or more <call>, <execNative>, and <transform> steps. No other steps are permitted. The contained steps can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.

<capture> Element

The <capture> element defines the files and resources that are to be captured as part of this snapshot. The capture occurs only after the steps in the <prepare> block have executed. When the capture is complete, the steps in the <cleanup> block will execute.

The <capture> element children consist of one or more <addFile>, <addSnapshot>, and <addResource> elements. The files and directories that are listed in this block are captured in the order specified. The contained children can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.

<addFile> ELEMENT

The <addFile> element is a child of the <capture> element and specifies a file that is to be captured as part of the containing snapshot.

ATTRIBUTES FOR THE <addFile> ELEMENT

The <addFile> element includes the following attributes:

• path – A required attribute that specifies the path name of a file or directory on the file system of the target host. This attribute can reference simple substitution variables.

• ownership – An optional attribute that specifies the ownership option for the captured file.

  One aspect of the installed state that is captured by the snapshot is file and directory ownership. This ownership is not the same as UNIX permissions. The ownership is more closely tied to the concept 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 change can be recognized and reported when the file is compared against its initial state. This feature helps to track 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, which is known as the owners table.

  The values of the ownership attribute have the following semantics:

  • SET_SELF – When the ownership is set in this way, the owners table is updated to contain a single entry for the associated file or directory. That entry lists the executing installed component and snapshot as owners. The entry also lists the capture area ID of the captured contents of the file or directory.

  • ADD_SELF – When the ownership is set in this way, the installed component and snapshot are added as additional owners and share the existing capture area ID as the previous owners.

  • ADD_TEMP – This value 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 ID of the other owners.

  If this attribute is omitted, the default value is SET_SELF.

• filter – An optional attribute of type boolean that describes whether to capture files, directories, or both.

  If the value of path is a directory, this attribute is used to indicate whether the directory itself, the files it contains, or both should be captured. If the value of path is not a directory, this attribute is ignored and the file is captured directly. If this attribute is omitted, the default BOTH is used.

  The values for this attribute are as follows:

  • DIRECTORIES

  • FILES

  • BOTH

• recursive – An optional attribute that indicates whether subdirectories should be recursively captured by using the current filter settings.

  If the value of path is a directory, this attribute indicates whether subdirectories should be recursively captured by using the current filter settings. If the value of path is not a directory, this attribute is ignored and the file is captured directly. The default value is true.

• displayName – An optional attribute that is a string to be included in the display when this snapshot entry is compared against another.

  This attribute can reference simple substitution variables.

<addSnapshot> ELEMENT

The <addSnapshot> element denotes that an external snapshot block should be executed and that its contents should be added to this snapshot.

Using an <addSnapshot> step is semantically equivalent to all of the following scenarios:

• 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

• Adding the <capture> steps of the called snapshot to the calling snapshot's capture block in place of the <addSnapshot> step

Make sure that the files that are referenced by the called and calling snapshot blocks do not conflict.

Any number of <addSnapshot> steps can appear within a <capture> element. The called snapshot itself can contain any number of <addSnapshot> steps within its <capture> element.

When files are added to a snapshot indirectly by using <addSnapshot> callouts, the topmost component that initiated the snapshot capture is considered to be the owner of the files, as opposed to the component that contained the <addFile> directive. Similarly, when a comparison is performed on a snapshot, only <diff> element <ignore> directives of the topmost component that initiated the snapshot are considered. The <diff> element <ignore> directives that are contained on components visited as a result of <addSnapshot> callouts are not considered.

The <addSnapshot> element has one required attribute of type entityName, blockName, which is the name of the external snapshot block to execute.

The <addSnapshot> element has the following child elements:

• <argList> – An optional element that is a list of arguments to pass to the snapshot block. This element can only appear one time.

• Installed component targeter – An optional element that identifies the component that contains the snapshot block. If this element is omitted, <thisComponent> is used.

<addResource> ELEMENT

The <addResource> element denotes a resource that is associated with the component that is to be captured as part of the containing snapshot. This element can 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, <addResource> is equivalent to the following statement:

  <addFile path="path-of-deployed-directory" filter="FILES" displayName="resourceSourcePath"/>

• If the associated resource is a directory resource with deployMode=REPLACE, <addResource> is equivalent to the following statement:

  <addFile path="path-of-deployed-directory" displayName="resourceSourcePath"/>

• Otherwise, the associated resource is a file-based resource, and <addResource> is equivalent to the following statement:

  <addFile path="path-of-deployed-file" displayName="resourceSourcePath"/>

<cleanup> 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. 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. Use cleanup blocks to remove any temporary files that are created by the prepare block.

The <cleanup> element children consist of one or more <call>, <execNative>, and <transform> steps. No other steps are permitted. The contained steps can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.

<controlList> Element

The <controlList> element is an optional child of the <component> element. This element lists the control blocks that are available for the component. If used, this element can only appear one time.

This element has a required child element, <control>, which is a control block. You can specify more than one <control> element.

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 can declare new <control> elements and override inherited ones, but it cannot remove elements that are declared by the base component.

<control> Element

The <control> element defines a control block that is available for this component. A control block is a sequence of steps that can be performed after the component has been installed. For example, a component for a database application might include control blocks to start or shut down the database. A <call> step can invoke a control block by name, which causes the control block steps to be executed in order.

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. See Shared Steps. The body is not included if the control block is declared abstract.

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.

Attributes for the <control> Element

The <control> element has the following attributes:

• access – An optional attribute of type accessEnum, which specifies the accessibility of the control block. These are the possible values:

  • PUBLIC – Access is unrestricted, which is the default value.

  • PROTECTED – Access is limited to derived components and entities that are in the same path.

  • PATH – Access is limited to entities that are in the same path.

  • PRIVATE – Access is limited to this component.

  Only PUBLIC blocks can be run directly from the component.

• modifier – An optional attribute of type modifierEnum, which specifies the override requirements for the control block. These are the possible values:

  • ABSTRACT – The block cannot include a body. Instead, the body must be specified by nonabstract derived components. A control block can only be declared abstract if the component is also declared abstract. An abstract block cannot be private. Nonabstract blocks must declare a body.

  • FINAL – The control block cannot be overridden by derived components.

  If this attribute is omitted, derived components can choose whether to override the block.

• name – A required attribute of type entityName, which is the name of the control block. This is referenced from a <call> step to execute the control.

• description – An optional attribute that is a string that describes the control block.

<diff> Element

The <diff> element is an optional child of the <component> element. This element contains a list of directives that are used by the comparison engine to run comparisons on this component. If used, this element can only appear one time.

The <diff> element has one child element, <ignore>, which is required. This element specifies a directory path to ignore during comparison. You can use the <ignore> element one or more times.

A derived component automatically inherits all of the ignore directives declared by its base component. The component can also declare additional ignore directives in its own <diff> element. Inherited directives cannot be removed.

<ignore> Element

The <ignore> element is a child of the <diff> element and specifies a file name path pattern to ignore when using this component in a comparison. This element is typically for files and directories that are created by the installed application, such as log files. The configurable attributes of this element can reference component substitution variables.

The <ignore> element has one required attribute, path, which is a glob-style pattern that matches the file name paths to ignore, for example, /logs/*.log. This attribute can reference component-scoped substitution variables.