Install-Only Steps for Components
This section describes steps that can only be used within an install block of a component.
All steps except the <deployResource> step can be used by both simple and composite components. The <deployResource> step can only be used by simple components.
<createDependency> Step
This step creates a persistent dependency of the current component on another component. When executed, this step first checks for an installed component that matches the given criteria. The step fails if no such component exists (just as with the <checkDependency> step). If a match is found, a persistent dependency is created between the matching component, the “dependee,” and the calling component, the “dependent.”
If more than one installed component matches the criteria, which is possible if no install path is specified, the latest match is used as the dependee. The persistent component is created with the name that is specified in the step. The name must be unique among all dependencies created in the install block.
After the persistent dependency is created, it remains until the dependent component is uninstalled. If the installation of the dependent component fails in a subsequent step after having created a persistent dependency, the dependency is removed immediately at the time of failure.
A given component might depend on any number of other components by executing a <createDependency> step for each. The <createDependency> steps should appear as the first steps within an install block so that the installation will fail prior to performing any real work if the dependencies are not satisfied.
The <createDependency> step has one required child element, which identifies the dependee component. The child element is an installed component targeter. See Installed Component Targeters.
Attributes for the <createDependency> Step
The <createDependency> step has one required attribute of type identifier, name, which is the name of the dependency to create. The name must be unique among all dependencies created by the current component.
Uninstallation Implications for the <createDependency> Step
A component cannot be uninstalled if installed components depend on it. When an uninstall block of a component is encountered, if one or more persistent dependencies exist for which the component is the dependee, the uninstallation fails immediately.
However, if component B is being uninstalled by another component A, dependencies created by A on B will not prevent B from being uninstalled, and will be implicitly removed when B is successfully uninstalled.
The dependee component can specify actions to uninstall its dependents by using a <dependantCleanup> block.
Reinstallation Implications for the <createDependency> Step
A component installation is considered to be a reinstallation if a preexisting component in the same version tree is installed on the same host and install path. A component can be reinstalled only if the new component also satisfies all the dependents of the original component. A component can always be reinstalled with the same version component. However, a component can only be reinstalled with a different version if the new version also matches the constraints specified in the <createDependency> step that created the persistent dependency.
When a simple install block of a component is encountered, the provisioning software determines if the installation will overwrite an existing installation. If so, the provisioning software finds all persistent dependencies for which the existing component is the dependee, and reverifies that the constraints of the dependency are still satisfied with the new component being installed. If any constraints are not satisfied, the installation of the new component fails, and the original component remains installed.
Otherwise, if and when the new component successfully completes its installation, the component becomes the new dependee on all persistent dependencies. The original component is considered to be uninstalled and all of the persistent dependencies for which it was the dependent are removed. This implies that the new component is responsible for recreating dependencies, as needed.
Naming Conventions for the <createDependency> Step
Dependency names follow this format: xxx2yyy. The xxx indicates the name of the dependent component, and yyy indicates the name of the dependee component.
For example, a WebLogic managed server might have a dependency called server2domain on its admin server and a server2cluster dependency on its containing cluster. This convention facilitates self-documentation of the nature of the dependency relationship and makes it readable for both the dependee and dependent relationships of a particular component.
<createSnapshot> Step
This step creates a snapshot of the current installed state of the component being installed. You can specify any number of <createSnapshot> steps within an install block.
The named snapshot block cannot declare any required parameters because the <createSnapshot> step does not support argument passing. Argument passing is not supported because it would also require support for argument collection and passing during a later comparison on the resulting snapshot.
A comparison performed on a composite component includes all snapshots that are created directly by that component. The comparison also includes the complete tree of snapshots that are created by the recursive installation of all nested component references. However, snapshots that are associated with top-level component references are not considered. Thus, such snapshots must be explicitly included in the snapshot of the composite component by using the <addSnapshot> capture directive.
In addition, nested components might have some interdependencies that make it necessary to defer snapshot capture until all such components are installed. One example is a nested component that deploys a directory and a nested component that deploys a file into that directory. In such interdependent cases, the containing component should install the nested components by using parameter passing or special install blocks that tell the nested component not to take the snapshot during their install. Then, have the snapshot block of the containing component include appropriate snapshots of the nested components by using the <addSnapshot> directive.
Attributes for the <createSnapshot> Step
The <createSnapshot> step has one required attribute of type entityName, blockName, which is the name of the snapshot block to execute within the component.
<install> Step
This step installs a component onto a target host, and causes the steps of the named install block of the targeted component to be executed.
The syntax of this step is as specified for the simple plan <install> step (see <install> Step), except that the component targeter can be omitted, in which case <thisComponent> is assumed.
When used within a component, this step is often used to call into another install block in the same component. In this case, the component is not considered to be installed until the outermost install block has completed its execution. Furthermore, the component is only considered to be installed on the host on which the install step was initially targeted, even if calls to other local install blocks were retargeted to other hosts.
This step can also be used within a composite component to install referenced components. The referenced components can be installed on hosts other than that on which the containing component is being installed. If the installation of the containing component fails, any nested referenced components that were successfully installed prior to the failure are implicitly uninstalled without executing an uninstall block. However, any top-level referenced components that were successfully installed prior to the failure remain installed.
<deployResource> Step
This step deploys the resource of the containing component and can only be used in an install block of a simple component. This step has no attributes or child elements.
A directory type resource where deployMode=ADD_TO has each of its contained files copied while preserving the directory structure. New directories are created, as needed. The existing directory structure and contents is unchanged, other than copying of resource contents. Individual file permissions and ownership are updated, as appropriate.
A directory type resource where deployMode=REPLACE is treated the same as deployMode=ADD_TO, except that any preexisting directory is recursively removed prior to deployment.
All other resources are copied, then have their permissions and ownership updated, as appropriate. Resources that are checked in as configurable undergo variable substitution prior to being copied. Configurable resources can reference any variable that is accessible to the component in which the resource was declared.
- © 2010, Oracle Corporation and/or its affiliates