External Component Substitution Reference Resolution

The value of an external component substitution reference is computed by first resolving the component referenced by primary-component. If a secondary-component is used as a primary-component, then the component containing the external component substitution reference serves as the initial current component used when resolving the primary-component. The component resolved by primary-component becomes the new current component. Then, each secondary-component in the secondary-component-list is resolved using the last resolved component as the current component. Finally, we lookup and return the variable named varname in the last resolved component.

The value of an external component substitution reference is computed based on the value of the named variable within the referenced component as of the time it was installed. It is an error to reference a variable name that is not declared by the installed component, or to reference a component that is not installed on the target host. It is also an error to reference a variable that is not accessible to the component or plan that declares the external component substitution reference. The variable is accessible if and only if the variable is declared with an accessible access mode, and the component declaring the component is accessible, and each of the primary and secondary components traversed to get to that component are accessible.

External component substitution references are computed at the time that they are encountered during a plan run (as opposed to at the start of the plan run). Therefore, actual installed component being referenced may change based on steps executed earlier in the plan. Furthermore, references to components installed on a host other than the current target host may be affected by other plans running concurrently on the other host. For predictable results, clients should only reference hosts included in the target set of the current plan run (so that they"re guaranteed to be locked), and should synchronize any install/uninstall operations on an externally referenced host within the plan using retargeting and/or series execution mode.

Here are some examples of external component substitution references, using explicit-external components:

:[component:installApache:label]
:[component:jdk#1.3:classpath]
:[component:webApp#2.4@{/usr/local}:bannerColor]
:[component(/):IIS global settings:install_path]
:[component:webApp@{:[webAppPath]}:bannerColor]

In the second to last example, the component is resolved that is installed on the root physical host of the current target host.

In the last line, webAppPath is resolved as the name of a simple substitution variable set in the associated component of the generation context, not a variable defined in the externally referenced component.

Here are some examples of external component substitution references, using nested and toplevel-components:

:[nestedRef:ref1:label]
:[toplevelRef:ref2:name]
:[toplevelRef(/):ref3@{/usr/local}:var1]

Here is an example of external component substitution references, using dependee-components:

:[dependee:app2domain:domainName]