External Component Substitution Variable References (N1 Grid Service Provisioning System 5.0 Plan and Component Developer's Guide)

N1 Grid Service Provisioning System 5.0 Plan and Component Developer's Guide

External Component Substitution Variable References

A variable setting value can include one or more external component substitution references. An external component substitution reference is one of the following:

:[primary-component:varname]
:[primary-component:secondary-component-list:varname]

Note that an external component substitution reference does not include any white space.

primary-component is one of the following:

explicit-external-component
system-service-component
system-type-component
targetable-component
secondary-component

secondary-component is one of the following:

nested-component
toplevel-component
dependee-component
container-component

secondary-component-list is a sequence of one or more colon-separated secondary-components.

varname is either a predefined substitution variable name or a dynamic substitution variable name that is declared by the referenced component.

Explicit External Component Expansion

An explicit-external-component explicitly specifies a component that is expected to be installed on a particular host in a particular location. It has the component resolution semantics of the <installedComponent> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

explicit-external-component has the following syntax:

component-target:explicit-component-reference

component-target specifies the host on which the specified component is installed and is one of the following:

component – Specifies the current target host in the generation context
component(host-redirect) – Refers to the host named by host-redirect (see Host Redirects)

explicit-component-reference is a reference to a component that is already installed on the target host that is specified by component-target. The explicit-component-reference minimally includes the installed component name, but can also include a version and an install path, as follows:

full-component-name
full-component-name#version
full-component-name@{path}
full-component-name#version@{path}

full-component-name is an absolute or relative reference to the specified component. A relative reference is expanded relative to the plan or component that contains explicit-component-reference.

path is the absolute install path name of the specified component, or a substitution variable reference that, when expanded, represents the absolute install path of the specified component. If path includes the } character, it must be escaped using the }} sequence.

System Service Component Expansion

A system-service-component specifies a system service component that is expected to be installed on the root physical host of the current target. It has the component resolution semantics of the <systemService> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

system-service-component has the following syntax:

systemService:system-service-name

If the system service is defined by a plug-in, system-service-name must be prefixed with the name of the plug-in that defines it.

System Type Component Expansion

A system-type-component specifies the component that is derived from a specified component type that is most recently installed on a particular host in a particular location. It has the component resolution semantics of the <systemType> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

system-type-component has the following syntax:

systemType:component-type-name
systemType:component-type-name@{path}
systemType(host-redirect):component-type-name
systemType(host-redirect):component-type-name@{path}

path is optional. If specified, path is the absolute install path name of the specified component or a substitution variable reference. The reference, when expanded, represents the absolute install path of the specified component. If path includes the } character, it must be escaped using the }} sequence.

host-redirect is also optional and indicates the host on which the component is installed. See Host Redirects.

If the component type is defined by a plug-in, component-type-name must be prefixed with the name of the plug-in that defines it.

`targetableComponent` Component Expansion

A targetable-component references variables that are associated with a targetable component and is similar to the <targetableComponent> targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

targetable-component has the following syntax:

targetableComponent
targetableComponent(host-redirect)

host-redirect is the name of a component targeting host. If unspecified, the host on which the plan is currently executing is used. These constructs resolve to the targetable component that is associated with a particular component targeting host. See Host Redirects.

Secondary Component Expansion

Nested Component Expansion

A nested-component specifies the component that is referenced by a nested component reference that is declared by the current component. It has the component resolution semantics of the <nestedRef> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

nested-component has the following syntax:

nestedRef:component-reference-name

component-reference-name is the name of a <componentRef> element where installMode=NESTED for the current component.

nested-component can only be used when the current component is a composite component. It can only be used as a primary-component when the external component substitution reference appears in a composite component. When used as a primary-component, it cannot be used as the default value of a component variable or override variable setting. This is because the referenced component will not yet have been installed when the variable is evaluated.

Top-Level Component Expansion

A toplevel-component specifies the component that is referenced by a top-level component reference that is declared by the current component. It has the component resolution semantics of the <toplevelRef> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

toplevel-component has the following syntax:

toplevelRef:component-reference-name
toplevelRef:component-reference-name@{path}
toplevelRef(host-redirect):component-reference-name
toplevelRef(host-redirect):component-reference-name@{path}

component-reference-name is the name of a <componentRef> element where installMode=TOPLEVEL for the current component.

path is the absolute install path name of the specified component, or a substitution variable reference. The reference, when expanded, represents the absolute install path of the specified component. If path includes the } character, it must be escaped using the }} sequence.

host-redirect is the host on which the referenced component is expected to be installed. The syntax for host-redirect is described in Host Redirects.

toplevel-component can only be used when the current component is a composite component. It can only be used as a primary-component when the external component substitution reference appears in a composite component. When used as a primary-component, it cannot be used as the default value of a component variable or an override variable setting. This is because the referenced component has already been installed.

Dependee Component Expansion

A dependee-component specifies the component on which the current component depends as a result of a dependency created by a <createDependency> step. dependee-component has the component resolution semantics of the <dependee> installed component targeter. See Installed Component Targeters in N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide.

dependee-component has the following syntax:

dependee:dependency-name

dependency-name is the name of a dependency that is created by the current component.

dependee-component can only be used as a primary-component when the external component substitution reference appears in a component. When used as a primary-component, it cannot be used as the default value of a component variable or an override variable setting. This is because the dependency will not yet have been created when the variable is evaluated.

Container Component Expansion

A container-component specifies the component that contains the current component as a nested reference.

container-component has the following syntax:

container

container-component can only be used as a primary-component when the external component substitution reference appears in a component that has been installed as a nested component by another “container” component.

Resolving External Component Substitution References

The value of an external component substitution reference is computed first by resolving the component that is referenced by primary-component. If secondary-component is used as a primary-component, the component that contains the external component substitution reference serves as the initial current component that is used when resolving the primary-component. The component that is resolved by primary-component becomes the new current component. Then, each secondary-component in secondary-component-list is resolved by using the last resolved component as the current component. Finally, the provisioning system looks up and returns the variable, varname, in the last resolved component.

The value of an external component substitution reference is computed based on the value of the specified variable in the referenced component at the time the component was installed. You cannot refer to a variable that is not declared by the installed component or to a component that is not installed on the target host. You also cannot refer to a variable that is not accessible to the component or plan that declares the external component substitution reference. The variable is accessible only if it is declared with an accessible access mode, the declaring component is accessible, and each primary and secondary component that is traversed to get to that component is accessible.

External component substitution references are computed at the time that they are encountered during a plan run, not at the start of the run. Thus, an actual installed component that is being referenced might change based on the steps executed earlier in the plan. Furthermore, references to components that are installed on a host other than the current target host might be affected by other plans that are running concurrently on the other host. For predictable results, only refer to hosts that are included in the target set of the current plan run because they are guaranteed to be locked. Also, synchronize any <install> or <uninstall> operations on an externally referenced host in the plan by using retargeting or series execution mode.

Example 6–2 Using External Component Substitution Variable References

The following are examples of external component substitution variable references that use explicit-external components:
:[component:installApache:sys.label] :[component:jdk#1.3:classpath] :[component:webApp#2.4@{/usr/local}:bannerColor]
In the following example, the provisioning system resolves the component that is installed on the root physical host of the current target host:
:[component(/):IIS global settings:install_path]
In this example, webAppPath is resolved as the name of a simple substitution variable that is set in the associated component of the generation context. It is not a variable that is defined in the externally referenced component.
:[component:webApp@{:[webAppPath]}:bannerColor]
The following examples show external component substitution variable references that use targetable-component:
:[targetableComponent:hostName] :[targetableComponent(host1):port]
The following are examples of external component substitution variable references that use nested-component and toplevel-component:
:[nestedRef:ref1:sys.label] :[toplevelRef:ref2:sys.name] :[toplevelRef(/):ref3@{/usr/local}:var1]

The following are examples of external component substitution variable references that use system-type-component and system-service-component:

:[systemService:com.sun.windows#Windows SS:classPath]
:[systemType:com.sun.weblogic#WL Target Type:serverName]
:[systemType(..):MyType@{/tmp}:var1]

The following is an example of an external component substitution variable reference that uses dependee-component:
:[dependee:app2domain:domainName]
The following is an example of an external component substitution variable reference that uses container-component:
:[container:sys.installPath]
The following is an example of a chained component reference. This reference assumes that the current target component is installed as a nested component of another container component. The container: part resolves to the component that contains the current component, which for this example is called X. The nestedRef:ref1 part resolves to the component that is referenced by component X by using its component reference named ref1, which is component Y. The toplevelRef:ref1 part resolves to the component that component Y refers to by using its component reference ref1, which is component Z. Finally, the provisioning system resolves and uses the value of the label attribute that is defined by component Z.
:[container:nestedRef:ref1:toplevelRef:ref1:sys.label]