<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.

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.

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