The componentRef Element

The <componentRef> element is a child of the <componentRefList> element and specifies a component referenced by this component.

Component refs have implicit PUBLIC access mode.

The componentRef Element attributes

componentRef modifier Attribute

The "modifier" attribute of the <componentRef> element specifies the override requirements for the component reference.

If ABSTRACT, the component reference <component> element is omitted and must be specified by non-abstract derived components. Component references may only be declared abstract if the component is also declared abstract. Non-abstract component references must declare a <component> element.

If FINAL, the component reference may not be overridden by derived components.

If unspecified, then derived components can choose whether or not to override the component reference.

componentRef installMode Attribute

The installMode attribute of the <componentRef> element specifies the way in which the referenced component should be installed and targeted thereafter. If the referenced component is installed as TOPLEVEL, then it can be used by any other component just as if it had been directly installed by a plan. However, if the referenced component is installed as NESTED, then its installation is implicitly scoped to that of the referencing component, and its services are only available to the referencing component.

Logically, a nested referenced component defines a finer-grained unit of functionality required by the referencing component, but not otherwise useful to other components. Whereas a toplevel referenced component defines services that will be used by the referencing component, but may 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 toplevel referenced component is not tied to that of the referencing component in any way. The referencing component may install a toplevel referenced component when it is installed, or the referenced component have been installed previously or later by other means. When the referencing component is uninstalled, a toplevel referenced component will remain installed unless it is explicitly uninstalled by the referencing component. Other components are also free to uninstall it.

The componentRef Child elements

1 May not be included in abstract componentRefs.

componentRef Inheritance and Overriding

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

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

A derived component may override a component reference of a non-final inherited component reference by redeclaring a component reference with the same name. When a component reference is overridden, the entire content 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, as described in the following section. The <component> element is specified if and only if the overriding reference is non-abstract.

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 non-abstract, then any abstract component references declared by the base component must be overridden by the derived component.