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