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.