<component> Element Overview

A component is enclosed within the <component> element. All versions of a component must have the same name and path. This element's attributes can reference component-scoped substitution variables.

Attributes for the <component> Element

The <component> element has the following attributes:

• xmlns – A required string that has a value of http://www.sun.com/schema/SPS.

• xmlns:xsi – A required string that has a value of http://www.w3.org/2001/XMLSchema-instance.

• xsi:schemaLocation – An optional string. The recommended value is http://www.sun.com/schema/SPS component.xsd.

• access – An optional attribute that specifies the accessibility of the component, which is how the component can be referenced by other components. These are the legal values:

  • PATH – The component can only be referenced by other components in the same path as this component. When access=“PATH”, you cannot directly install the component, and it can only be included in other components by using a nested reference.

  • PUBLIC – The component can be referenced by any component and is not bound by the restrictions imposed by PATH access. This is the default value.

• modifier – An optional value of type modifierEnum, which specifies the following override requirements for the component:

  • ABSTRACT – Identifies the component as an abstract component. An abstract component serves only as a base component for other components to extend and cannot be installed. Only an abstract component is permitted to declare abstract child elements.

  • FINAL – Identifies the component as a final component, which means that the component cannot be extended by another component.

  If this attribute is omitted, the component can be extended and installed, which is the default.

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

• path – An optional value of type pathName, which is the absolute path of the component. If this attribute is omitted, the root path (/) is the default value. The value must name a folder that exists at the time that the component is saved.

• description – An optional string that is a description of the component.

• label – An optional string that is a brief description of the component.

• softwareVendor – An optional string that is the vendor name of the software application that is modeled by the component.

• author – An optional string that is the name of the component's author.

• version – A required value of type schemaVersion, which is the version of the component schema. Currently, the only permitted values are 5.0 and 5.1.

  The 5.1 version of the schema is backward compatible with the 5.0 version.

• platform – An optional string that specifies the name of the host set that includes the hosts that are valid physical targets on which this component can be installed.

  If this attribute is omitted, any host that contains the Remote Agent application and that is a supported platform is a valid physical target. Otherwise, the physical targets for any plan that installs this component must be a subset of the hosts that are contained in the specified host set. If the physical targets include a host that is not part of the specified host set, the plan issues a runtime error. These plan runtime errors are reported as preflight errors. A component save time error is issued if you specify a name that does not correspond to a supported platform host set. Platform host sets are all prefixed with the system# plug-in name. If a component platform host set is unsupported, a new version of the component cannot be checked in until the platform is changed. Any operation on the existing component version that refers to the unsupported platform host set will fail.

• limitToHostSet – An optional string that specifies the name of the host set that contains the hosts that are valid targets for this plan.

  If this element is omitted, all hosts are valid targets. Otherwise, the specified targets must be a subset of the hosts that are included in the named host set. If the targets include a host that is not part of the specified host set, the plan issues a runtime error. These plan runtime errors are reported as preflight errors. A component save time error occurs when you specify a name that does not correspond to an existing, supported host set. If the specified host set is one that is defined by a plug-in, pluginName must be a prefix to the host set name, such as pluginName#hostSetName.

  These are the two main differences between the platform and the limitToHostSet attributes:

  • platform names one of the predefined platform host sets, whereas limitToHostSet names a user-defined host set. Therefore, if you want to limit installation based on a custom host set, use limitToHostSet.

  • When a component is targeted at a virtual host, limitToHostSet is tested against the virtual host, whereas platform is tested against the root physical host of that virtual host.

  Therefore, if you set limitToHostSet but not platform, a component can be installed on a particular set of virtual hosts that might reside on different physical platforms (as is the case with WebLogic applications). However, if you set platform but not limitToHostSet, a component can be installed on any host that is rooted by a physical host with the given platform. If you set both, you can constrain both degrees.

• installPath – A required string that is only for nonderived components. This path is used when the component is installed. For simple components, this value also serves as the root directory in which to install the component's resources. The path is stored in universal format when an instance of this component is installed. See Universal Install Path Format.

Except for installPath and limitToHostSet, component attributes are not inherited.

The installPath attribute is inherited and cannot be overridden by derived components. However, the base component can use component variables when specifying its value, and the value of these variables can be overridden.

The limitToHostSet attribute is inherited and can be overridden by derived components only if the base component did not specify limitToHostSet.

Because the limitToHostSet value names a mutable, user-managed entity, the relation of host set cannot be reasoned about in the same way as platforms.

The platform attribute is not inherited. However, the platform attribute value of a derived component can be no more general than that of the base component. If platform is not specified in a derived component, platform cannot be specified (or must be specified as any) in the base component.

Child Elements of the <component> Element

The <component> element has the following child elements, which must appear in the order shown. These child elements might have their own child elements, attributes, or both.

• <extends> – Declares the base component from which the component is derived

• <varList> – Lists the component-scoped variables that are used by the component and its resources

• <targetRef> – Declares that the component is “targetable”

• <resourceRef> – Specifies the resource managed by the component

• <componentRefList> – Lists the components that are referenced by this component

• <installList> – Contains one or more named blocks of <install> steps

• <uninstallList> – Contains one or more named blocks of <uninstall> steps

• <snapshotList> – Contains one or more named <snapshot> blocks

• <controlList> – Lists the <control> blocks that are available for the component

• <diff> – Lists the directives that are used by the comparison engine to perform comparisons on this component