Installed Component Targeters

This section describes the elements that identify an installed component as the target of the containing step (for example, control service call). All targeters cannot be used with all targeted steps. Each targeter specifies the steps with which it can be used.

• <installedComponent> Installed Component Targeter

• <systemService> Installed Component Targeter

• <systemType> Installed Component Targeter

• <thisComponent> Installed Component Targeter

• <superComponent> Installed Component Targeter

• <nestedRef> Installed Component Targeter

• <allNestedRefs> Installed Component Targeter

• <toplevelRef> Installed Component Targeter

• <dependee> Installed Component Targeter

• <allDependants> Installed Component Targeter

• <targetableComponent> Installed Component Targeter

<installedComponent> Installed Component Targeter

The <installedComponent> element identifies a particular installed component that is assumed to be installed on the target host.

This element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

This targeter matches the specified component directly and cannot be used to match derived instances of that component. Use the <systemType> targeter to target components that are derived from a particular type.

Attributes for the <installedComponent> Targeter

This targeter has the following attributes:

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

• path – An optional attribute of type pathReference, which is the path of the component. If this attribute is omitted, the path of the containing entity is assumed.

• version – An optional attribute of type version, which is the version of the installed component. If this attribute is omitted, the most recently installed component, regardless of the version, is used.

• versionOp – An optional attribute that specifies the operator to use when comparing the version attribute with versions of components that are installed on the target host. If more than one installed component applies, the most recently installed component is used. These values are permitted: =, >=, and >.

  The >= operator is used by default. If version is not specified, versionOp is ignored.

• onlyCompat – An optional attribute that specifies the components that should match.

  If the value is true, only components that are call compatible with the component of version version should be matched. A component of version version must exist. By default, the value is false. If version is omitted, this element is ignored.

• installPath – An optional attribute that is the install path of the installed component. If this attribute is omitted, the most recently installed component in any path is used. The value is converted to universal format prior to component resolution. This attribute can reference simple substitution variables.

• host – An optional attribute that is the host on which the component is installed. By default, host is the current host. See the description of the host attribute in Attributes for the <retarget> Step. This attribute can reference simple substitution variables.

<systemService> Installed Component Targeter

The <systemService> element identifies a particular system service component that is assumed to be installed on the current physical host. If the system service is defined by a plug-in, the service name should be prefixed with the plug-in name, such as pluginName#serviceName.

This element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

Use of the <systemService> targeter implicitly retargets to the root physical host of the current host. If you need to target a system service on a different host, a <retarget> step must be used. You cannot otherwise specify a new host within the <systemService> targeter.

Attributes for the <systemService> Targeter

The <systemService> targeter has one required attribute of type systemName, name, which is the name of the system service component. If the system service is defined by a plug-in, the system service name should be prefixed with the plug-in name, such as pluginName#serviceName.

<systemType> Installed Component Targeter

The <systemType> element 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 component that was most recently installed is used.

The <systemType> element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

Attributes for the <systemType> Targeter

The <systemType> targeter has the following attributes:

• name – A required attribute of type systemName, which is the name of the system type component. If the system type is defined by a plug-in, the system type name should be prefixed with the plug-in name, such as pluginName#typeName.

• installPath – An optional attribute that is the install path of the desired component. The value is converted to universal format prior to component resolution. This attribute can reference simple substitution variables.

• host – An optional attribute that is the host on which the component is installed. By default, host is the current host. See the description of the host attribute in Attributes for the <retarget> Step. This attribute can reference simple substitution variables.

<thisComponent> Installed Component Targeter

The <thisComponent> element specifies that the component that contains the step should be used as target of the step. Only steps that are contained in a component can use this targeter. This element has no attributes.

The <thisComponent> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

If the steps listed do not contain a component targeter element, <thisComponent> is assumed by default.

<superComponent> Installed Component Targeter

The <superComponent> element specifies that the base component of the component that contains the step should be used as target of the step. Only steps that are contained in a derived component can use this targeter.

The <superComponent> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps. This element has no attributes.

This targeter always binds to the base component's definition of the step in question, even if the derived component overrides it.

<nestedRef> Installed Component Targeter

The <nestedRef> element identifies a nested component reference declared or inherited by the current composite component. Only steps that are in a composite component can use this targeter.

The <nestedRef> element can be used as a targeter for the <checkDependency>, <call>, <uninstall>, and <addSnapshot> steps.

The specified component reference is assumed to already be installed by the calling component. Otherwise, an error is issued. If the nested component reference was installed on a host other than the current target host, use of the <nestedRef> targeter implicitly retargets the associated step to that host.

Attributes for the <nestedRef> Targeter

The <nestedRef> targeter has one required attribute of type identifier, name, which is the name of a nested component reference in this component.

<allNestedRefs> Installed Component Targeter

The <allNestedRefs> element identifies the set of all nested component references that are declared or inherited by the current composite component. Only steps within composite components can use this targeter.

This element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

This targeter can identify any number of components. If it identifies no components, the step is a no-op. If it identifies more than one component, the step is semantically expanded as if a separate occurrence of the step that uses the <nestedRef> targeter exists for each of the identified components. The steps are executed serially rather than in parallel. The ordering of the steps varies based on the step type. If the execution of the step on one of the components causes an error, the step is not executed on the remaining matching components.

When used as a targeter for a <call> or <addSnapshot> step, this targeter matches all of the nested component references that are currently installed by this component. The component matches are in the order of installation.

When used as a targeter for an <uninstall> step, the targeter matches all of the nested component references that are currently installed by this component. The component matches are in the reverse order of installation.

<toplevelRef> Installed Component Targeter

The <toplevelRef> element identifies a top-level component reference that is declared or inherited by the current composite component. Only steps that are in composite components can use this targeter.

The <toplevelRef> element can be used as a targeter for the <checkDependency>, <createDependency>, <call>, <uninstall>, and <addSnapshot> steps.

This targeter is semantically equivalent to the <installedComponent> targeter, except that the name, path, and version attributes are predefined based on the referenced component. See <installedComponent> Installed Component Targeter.

Attributes for the <toplevelRef> Targeter

The <toplevelRef> targeter has the following attributes:

• name – A required attribute of type identifier, which is the name of a top-level component reference in this component.

• versionOp – An optional attribute that specifies the operator to use when comparing the version of the referenced component with versions of components that are installed on the target host. If more than one installed component applies, the most recently installed component is used.

  These values are permitted: =, >=, and >. If this attribute is omitted, >= is used.

• onlyCompat – An optional attribute that specifies the components that are matched. If true, this attribute specifies that only components that are call compatible with the referenced component should be matched. The default value is false.

• installPath – An optional attribute that is the install path of the referenced component. If this attribute is omitted, the most recent installation of the referenced component in any path is used. The value is converted to universal format prior to component resolution. This attribute can reference simple substitution variables.

• host – An optional attribute that is the host on which the referenced component is installed. By default, host is the current host. See the description of the host attribute in Attributes for the <retarget> Step. This attribute can reference simple substitution variables.

<dependee> Installed Component Targeter

The <dependee> element identifies an installed component on which the calling component has a declared dependency that was created by <createDependency>. Only steps that are in components can use this targeter.

The <dependee> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

Attributes for the <dependee> Targeter

The <dependee> targeter has one required attribute of type identifier, name, which is the name of a dependency that is created by this component.

<allDependants> Installed Component Targeter

The <allDependants> element identifies the set of installed components that have a declared dependency on the calling component, which was created by <createDependency>. Only steps in components can use this targeter.

The <allDependants> element can be used as a targeter for the <call>, <uninstall>, and <addSnapshot> steps.

This targeter functions similarly to the <addNestedRefs> targeter in that it causes the containing step to be mapped over all of the matching components. The order of the mapping over the dependent components is unspecified.

Attributes for the <allDependants> Targeter

The <allDependants> targeter has one required attribute of type identifier, name, which is the name of a dependency that is created on this component by other components.

<targetableComponent> Installed Component Targeter

The <targetableComponent> element identifies a targetable component that is associated with a particular component targeting host.

The <targetableComponent> element can be used as a targeter for the <call>, <uninstall>, <checkDependency>, <createDependency>, and <addSnapshot> steps.

Attributes for the <targetableComponent> Targeter

The <targetableComponent> targeter has one optional attribute, name, which is the name of a component targeting host. If this attribute is omitted, the value is the current target host. This attribute can reference simple substitution variables.

Universal Install Path Format

You can specify an install path within an installed component reference. In these cases, the installPath attribute value is converted to universal format before the installed component reference is resolved. This conversion occurs because the install path of the installed component is also stored in universal format.

In universal format, all occurrences of the path separator in the install path are replaced by a slash (/). The path separator is specific to the operating system that is running on the master server. Trailing slashes are dropped. The root install path (/) is not converted to the empty path.

When the Master Server application is running on UNIX based systems, trailing slashes are ignored. Thus, both /opt/apache/ and /opt/apache can be used to refer to the component that is installed in the /opt/apache directory.