Component Install-only Steps

This section lists steps that may only be used within an install block of a component (may be either simple or composite).

createDependency Step

A step used to create a persistent dependency of the current component on another component. When executed, this step first checks for an installed component matching the given criteria, and fails if no such component exists (just as with the <checkDependency> step). If match is found, then a persistent dependency is created between the matching component (the "dependee") and the calling component (the "dependant"). Note that if multiple installed components match the criteria (possible when no install path is specified), then the latest is used as the dependee. The persistent component is created with the name specified in the step. The name must be unique amongst all dependencies created in the install block.

Once created, the persistent dependency remains until the dependant component is uninstalled. Note that if the installation of the dependant component fails in a subsequent step after having created a persistent dependency, then the dependency is removed immediately at the time of failure.

A given component may depend on any number of other components by executing a <createDependency> step for each. It is recommended (but not required) that the createDependency steps appear as the first steps within an install block so that the installation fails prior to doing any real work if the dependencies are not satisfied.

createDependency Step attributes

createDependency Step Child elements

createDependency Step Uninstall Implications

A component may not be uninstalled if there exist installed components that depend on it. When an uninstall block of a component is encountered, if there exists one or more persistent dependencies for which the component is the dependee, then the uninstall fails immediately. However, if a component B is being uninstalled by another component A, then 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 dependants using a <dependantCleanup> block.

createDependency Step Reinstall Implications

A component install is considered a reinstall if there is a pre-existing component in the same version tree that is installed on the same host and install path. A component may be reinstalled if and only if the new component also satisfies all the dependants of the original component. A component can always be reinstalled with the same version component, but 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 component.

When a simple install block of a component is encountered, we determine if the install will overwrite an existing install. If so, then we find all persistent dependencies for which the existing component is the dependee, and re-verify that the constraints of the dependency are still satisfied with the new component being installed. If any are not satisfied, the install of the new component fails, and the original component remains installed. Otherwise, if and when the new component has successfully completed its install, it becomes the new dependee on all persistent dependencies. Also note that when the install of the new component successfully completes, then the original component is considered uninstalled, and all the persistent dependencies for which it was the dependant are removed. This implies that the new component is responsible for recreating dependencies as needed.

createDependency Step Naming Conventions

By convention, dependencies are named using the convention "xxx2yyy", where xxx in some way indicates the name of the dependant component, and yyy in some way indicates the name of the dependee component. For example, a WebLogic managed server might have a "server2domain" dependency 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 dependant relationships of a particular component.

createSnapshot Step

A step used to create a snapshot of the current installed state of the component being installed. Any number of <createSnapshot> steps may appear within an install block.

The named snapshot block may not declare any required parameters, as the createSnapshot step does not support argument passing. Argument passing is not supported because doing so would also require support for argument collection and passing at the time a comparison is later performed on the resulting snapshot.

When a comparison is performed on a composite component, it includes all snapshots created directly by that component, as well as the complete tree of snapshots created by the recursive installation of all nested component references. However, snapshots associated with toplevel component references are not considered, and therefore must be explicitly included in the snapshot of the composite component using the <addSnapshot> capture directive, as appropriate.

Also note that nested components may have some inter-dependencies that make it necessary to defer snapshot capture until all such components are installed. A nested component that deploys a directory and a nested component that deploys a file into that directory is an example of such an inter-dependence. In these cases, it is recommended that the containing component install the nested components using parameter passing or special install blocks that tell the nested component not to take the snapshot during their install, and then have the snapshot block of the containing component include appropriate snapshots of the nested components using the <addSnapshot> directive.

createSnapshot Step attributes

install Step

A step used to install a component onto a target host. It 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, except that the component targeter may be omitted, in which case <thisComponent> is assumed.

When used within a component, this step is often used to call into another existing install block in the same component. In this case, the component is not considered installed until the outermost install block has completed its execution. Furthermore, the component is only considered 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 composite components to install referenced components. The referenced components may be installed on hosts other than that on which the containing component is being installed. Note that if the install of the containing component fails, then any nested referenced components that were successfully installed prior to the failure are implicitly uninstalled without executing an uninstall block. However, any toplevel referenced components that were successfully installed prior to the failure remain installed.