Installable Unit Deployment Descriptor Specification Version 1.0

3.4.3           ConditionedIU

ConditionedIU is the generic type describing any contained IU defined within the root IU. Two compositions of this type are defined by a root IU: one is for the base content (installableUnit) while the other is for features (selectableContent).

IUs that can appear in an IU aggregate have an associated condition. The condition is a boolean variable expression. When the condition is false, the IU is not selected for install.  IUs defined within the aggregate may have siblings. A sequence number may be associated to the IU to specify the order in which the IU should be processed with respect to its siblings. 

3.4.4           RootIU.rootInfo

The rootInfo element defines characteristics of the root IU instance, such as the schema version on which it is based and the size of all files associated to artifacts defined in this root IU.

3.4.5           RootIU.features

A root IU may define zero or more features. Either each feature represents a top-level IUs defined inline within the RootIU or it is a reference to a feature in a referenced, separately packaged IU. In both cases, the IU referred to by the feature definition MUST be defined within the root IU selectable content composite.

3.4.6           RootIU.groups

The root IU may define zero or more groups of features (installation groups). Each group represents a combination of installable units that could be chosen for a given configuration or role, e.g. minimal versus typical; administrator versus developer versus client.

3.4.7           RootIU.topology

The root IU topology is a composite of one or more target definitions. A target can be a hosting environment onto which one or more IUs are to be deployed, or it can be a generic resource that is needed for the proper functioning of the solution. Ordinary targets pre-exist the solution deployment. Deployed targets are defined in the topology to represent resources that are created by instantiating an installable unit. 

3.4.8           RootIU.customCheckDefinitions

The customCheckDefinitions element includes definitions of check artifacts. Each artifact is a descriptor of actions that need to be performed on a target to establish if the latter satisfies some given requirements. Some of the actions defined in a check artifact may specify the execution of custom code. Multiple checks defined in different IUs may need to reuse the same custom check artifact. For this reason, the identification of check artifacts is factored out in the root IU.

3.4.9           RootIU.requisites

In addition to IUs that are part of the aggregate, the root IU may define requisite IUs, i.e. bundled packaged IUs, which may be installed on a target to satisfy a software requirement.

3.4.10      RootIU.files

The files element of the root IU is a composite of File definitions. Each File definition includes a file identifier. Any element within a root IU that is associated to a physical file declares that association by means of a reference to the corresponding file identifier. Examples of elements associated to a physical file are Referenced IUs and bundled requisite IUs. Actions specified within install artifacts  (see Section 9.4) may also contain references to physical files that need to be bundled with the root IU. These files need to be defined in the files element.

 

 

 

 

 

4         Software Change Management

The following data-flow diagram provides a model for the process involved in a software change. This model is provided as an illustrative example and alternative processes MAY be supported by an implementation of an install runtime. The process is a sequence of five logical activities: Environment Checks, Input, Dependency Check, Change and Register. These activities interact with the target hosting environment, and the installable unit database. The hosting environment (e.g. a configured operating system image) is the actual destination of the software being installed. The installable unit database is the repository holding information about the installable unit configuration for a set of hosting environments within a given scope (for example those on a single machine, or those within a complete administrative domain). The user provides input, in this process, either interactively or via a response file, and that input drives the activity of a software installer program.

 

Figure 5: Model of the software change management process

The rectangles at the bottom of Figure 5 represent entities defined in this specification:

The rectangle on the left represents the IU descriptor, conforming to the IUDD XML descriptor defined by this specification.

The rectangles on the right side represent artifacts associated to an SIU or to a CU. An SIU or CU may define multiple artifacts, each one associated to a different type of change (operation). Each artifact includes one artifact descriptor defining actions – such as the ones for creating or removing files on an operating system environment. Action definitions in the artifact descriptor are interpreted on the IU’s hosting environment to implement the change, and may reference files that need to be available when the actions are performed. 

The following list provides a description of the five logical activities illustrated in   Figure 5:

• Environment Checks.
  
  Gather information about the current environment (e.g. the presence of installed software on the target system). This activity generally executes before entering into the interactive stage of an attended installation or other change management operation, because the information may be used by an installer to determine the additional input that the user should provide during an interactive install. The environment checks should not be affected by user input: any variable contained in the specification of a check, if any, should have a well-defined initial value.
  
  
• Input.
  
  Obtain replacement values for parameters defined in a package, either through interactive user input or from a response file.
  
  
• Requirements Checks.
  
  Ensure that all requirements stated in the IU descriptor for a given type of change are satisfied before starting the change.
  
  
• Change.
  
  Perform the requested change operation on the installable unit, such as Create, Configure or Delete. The full list of change management operations, and the corresponding states of the installable unit, are described in section 4.2.
  
  
• Register.
  
  Persist information about the installable unit. For a Create operation, this information may include the identity of the newly created IU instance,  its target, its relationships to other installable units, and the values of variables used in its installation.

 

4.1 Hosting Environments

Software deployment has been traditionally designed and implemented as a process by which a software package (artifact) is installed on the running operating system image on one or more physical computers. In general, deployment of a software component (e.g. a database client) on one target needs to be coordinated with deployment of a different software component (e.g. a database server) onto another target.

 

“Hosting Environment” is a term used to denote the target of a software component with specific characteristics. Therefore, the term “OS hosting environment” is used to denote the hosting environment of traditional software products that are installed on an operating system, while the term “J2EE hosting environment” is used to denote a J2EE application server hosting J2EE applications.  Other hosting environment types may be defined, such as RDBMS databases, messaging systems, and other middle-ware.

4.2 Software Life-Cycle Operations

The following state diagram applies to an instance of any installable unit (SIU or aggregate). During its life-cycle an IU instance makes state transitions as a consequence of Change Management (CM) operations being applied to it. A CM operation MAY require an artifact specifying the actions to be executed on the hosting environment.

 

Figure 6: State diagram of an installable unit instance.

Error states that result from errors encountered when performing any of the indicated operations are not covered in this specification, and are not shown in the above diagram.

 

The following sections 4.2.1 to 4.2.10 describe the operations that create an IU instance, apply updates and configuration to that instance and delete the instance when it is no longer needed. The descriptions focus on the meaning of the operation for an SIU. Applying updates to an IU aggregate is discussed in Section 11. Ordering of install, applying to both Create and Update, is defined in Section 12.

4.2.1           Create

The Create operation creates a new instance of an SIU. The Install artifact associated to the SIU, see Section 9.4, defines the actions to be executed on the hosting environment to instantiate the SIU. 

The newly created IU instance transitions directly to the Usable state if no InitialConfig artifact is specified and there are no sibling configuration units defined in the same aggregate. Otherwise, the instance enters the Created state and an InitialConfig operation is needed to bring the instance to the Usable state.

On some hosting environments, the operation MAY be used to overwrite an existing instance of the SIU. The end result SHOULD be the same that would be obtained by performing the Create operation after applying the Delete operation to the existing instance.

An SIU may define a new base, an IU update or a temporary fix. An update can be full, in which case it is possible to use if for a fresh install; or incremental, in which case it must be applied to an existing instance.  The Create operation can only be performed for an SIU defining a new base or a full update. An SIU defining a temporary fix or an incremental update can only be applied to an existing instance using the Update operation. 

4.2.2           Update

The Update operation updates an existing instance.  The SIU defining an update or temporary fix contains a declaration of the version range of a base IU instance onto which it can be applied (update base). The Install artifact associated to the SIU, see Section 9.4,  defines the actions to be executed on the hosting environment to update the base instance. 

After the update, the version of the updated instance is changed to reflect the version specified by the SIU update.

The updated IU instance transitions directly to the Usable state if no Migrate artifact is specified and there are no sibling configuration units defined in the same aggregate. Otherwise, the instance enters the Updated state and the Migrate operation is needed to bring the instance to the Usable state.

The update may be applied in undo-able mode.  In this case, any resources (e.g. files) associated to the instance being updated that are being replaced or modified need to be saved, in order to support the roll-back of the update.

SIU updates and fixes may supersede fixes that are already applied to the instance being updated.

4.2.3           InitialConfig

The InitialConfig operation applies the initial configuration to an instance of the installable unit that is in the Created state, causing the transition to the Usable state. The operation can only be performed for an SIU defining a new base or a full update. The operation CANNOT be performed for an SIU defining a temporary fix or an incremental update. 

The InitConfig artifact associated with the SIU, see Section 9.4, defines actions to be executed on the hosting environment to make a created instance usable. This artifact implements the non repeatable part of the initial configuration.  

Sibling configuration units MAY be defined in the same IU aggregate to implement the repeatable part of the initial configuration. These configuration units are applied at the end of the InitialConfig operation, after the InitConfig artifacts have been processed for all SIUs in the whole root IU. See Section 4.3.

4.2.4           Migrate

The Migrate operation applies configuration to an installable unit  instance that is in the Updated state, causing the transition to the Usable state.  The operation can only be performed for an SIU defining an update (full or incremental). The operation CANNOT be performed for a fix.

The Migrate artifact associated with the SIU, see Section 9.4, defines actions to be executed on the hosting environment to make an updated instance usable. Actions in the artifact set the configuration by using existing installable unit instance data: the actions may implement the  migration of configuration data used in the previous version within the instance being superseded. The Migrate artifact implements the non repeatable part of the configuration process. 

Sibling configuration units MAY be defined in the same IU aggregate to capture the repeatable part of the configuration process. These configuration units are applied at the end of the Migrate operation, after the Migrate artifacts have been processed for all SIUs in the whole root IU. See Section 4.3.

4.2.5           Configure

The Configure operation applies artifacts associated with configuration units, see Section 10.2, which modify the configuration of a resource (topology target). The operation can be used to re-configure an installable unit instance. The operation can be re-applied multiple times to change the configuration of  resources.

The Configure operation SHOULD be supported with two execution modes: full and delta. 

In full mode, the operation applies all CUs defined in the base IU, all updates and all of the fixes to the latest level.

In delta mode, the operation can be applied to process either the set of CUs associated to the latest  update level or the CUs associated to one of the fixes that were applied to the latest level.

When a full IU is applied as an update to an existing instance, all CUs associated to aggregates of the base that are not obsoleted are replaced, see Section 11.1.  

4.2.6           VerifyIU

The Verify IU operation performs integrity checking of an installable unit instance with respect to its current state (Created, Updated, Usable). The final state is the same as the initial state unless the integrity checks fail, in which case the unit is put in an  error state.

A VerifyInstall artifact MAY be associated to an SIU, see Section 9.4. If specified, the artifact defines actions to be executed on the hosting environment to perform integrity checking of the SIU instance. Some integrity checking MAY be possible on some hosting environments without specifying an artifact.  

4.2.7           VerifyConfig

The VerifyConfig operation uses the VerifyConfig artifact, see Section 10.2,  to verify the configuration of a manageable resource.   

4.2.8           Repair

Some implementations MAY support the repair operation to perform the repair of an installable unit instance that failed a previous verification (VerifyIU). The installable unit instance remains in the error state if there are parts whose state was found in error for which a repair capability is not implemented. The Repair operation has no associated artifact.

4.2.9           Delete

The delete operation deletes an existing IU instance from the hosting environment.

The Uninstall artifact associated with the SIU, see Section 9.4, defines the actions to be executed on the hosting environment to remove resources (e.g. files) created as part of the instance. 

Some hosting environments MAY support using the install artifact for both the Create and the Delete operation. In that case, the install artifact is processed by the Delete operation to identify resources created during install that need to be removed.

The IU instance may have gone through multiple updates during its lifecycle. The semantic of the Delete operation is that all resources created as part of the IU initial creation and subsequent updates SHOULD be removed, unless they already existed when the instance was first created (or updated) in which case they SHOULD NOT be removed.

4.2.10      Optional operations: Undo and Commit

Undo support is OPTIONAL. Each hosting environment that can be the target of IU lifecycle operations specifies which operations, if any, can be performed in undoable mode. The  number of  levels of the Undo stack are also specified by the hosting environment. The release of backup resources MAY be controlled by the explicit invocation of a Commit operation. A hosting environment MAY implement an automatic Commit (e.g. because it does not implement more that a single undoable operation for the same IU instance).

The semantic of the Undo operation is explained below, by contrast to the Delete operation.

The result of applying Undo to an operation is to revert the IU instance to a previous state. For example, applying the Undo after an Update will revert the IU instance to its state prior to the update, while Delete would remove the instance. The Undo applied to a new IU instance after Create would produce the same effect of the Delete operation if the Create did not cause any pre-existing resources (e.g. shared files or registry entry) to be modified. While if the Create did modify or remove some pre-existing resources, these SHOULD be restored by Undo while Delete would leave the modified resources in their current state. 

In some cases, restoring the previous state of a shared resource may not be desirable, namely when the resource has been subject to further modifications after the backup copy was created.  Also, artifacts may contain actions that cannot be executed in undoable mode. The conditions that MAY limit Undo support on a given hosting environment are specified by each implementation. In particular, actions that can be defined in the install artifacts MAY support the specification of the desired behavior when the action should be undone.

4.3 The configuration process

InitialConfig and Migrate artifacts SHOULD only cover the non-repeatable part of an IU instance configuration so that they are NOT normally re-applied.

An implementation MAY support re-applying the InitialConfig and Migrate[1] artifacts on an IU instance that is already in the Usable state. This MAY be done in an attempt to restore a configuration baseline in case of a malfunction, although this MAY generally cause loss of data[2].

Configuration units can be included at any aggregate IU level within the root IU to define the repeatable part of the configuration process. CUs are used to configure resources created by installing the IU and other resources on which the IU is dependent for being usable.

Resources created by installing an IU may be configured by CUs targeted to the same hosting environment where the IU was deployed, or by CUs targeted to resources that were created by the IU install process (see deployed targets in section 5.6.4). 

When Configuration Units (CU) are defined in an aggregate IU, that IU cannot be considered Usable before the associated configuration have been applied. However, it SHOULD be possible to apply all configuration units at the end of the Create or Update process, when all the InitConfig and Migrate artifacts have been processed.

See Section 12.5.1 for a motivation of the above rule in a scenario where multiple chained dependencies need to be installed during an Update.  

Configuration units are applied the first time during the InitialConfig operation. In this case, configuration units SHOULD be applied after all InitConfig artifacts for all SIUs in the whole root IU have been processed, without requiring the explicit invocation of a separate Configure operation to apply the configuration units. 

Configuration units can be successively processed multiple times by invoking the Configure operation to change (or to re-apply) the current configuration.

Consistently, configuration units are applied during the Migrate operation. These configuration units SHOULD be applied after all Migrate artifacts, without requiring the explicit invocation of a separate Configure operation.

Only the new CUs introduced by the update or fix are applied during the Migrate process.

The Create operation leaves an aggregate IU instance directly in the Usable state if the IU descriptor specifies no Configuration Unit for that IU and SIUs under the aggregate specify no InitConfig artifacts. Similarly, the Update operation leaves the IU instance in the Usable state if no CUs are defined for the aggregate and SIUs under the aggregate specify no Migrate artifacts.

 

5         Installable Unit Deployment Descriptor

The Installable Unit Deployment Descriptor (IUDD) is the XML instance document defining a root IU. The IUDD defines a single instance of the iudd:rootIU element.

A number of attributes must be specified for the root element iudd:rootIU in order to make it possible to locate the schema files. The following XML fragment illustrates these attributes for a simple root IU whose content is targeted exclusively at the operating system hosting environment:

<?xml version="1.0" encoding="UTF-8"?>

 

<iudd:rootIU xmlns:iudd="http://www.ibm.com/namespaces/autonomic/solutioninstall/IUDD" xmlns:sig="http://www.ibm.com/namespaces/autonomic/solutioninstall/Signatures" xmlns:OSRT="http://www.ibm.com/namespaces/autonomic/OS_RT"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/namespaces/autonomic/solutioninstall/IUDD iudd.xsd "

IUName="MyRootIU" targetRef="MyTargetOperatingSystem">

 

The name prefix (xmlns:prefix) and schema location (xsi:schemaLocation) are already specified in the main schema file for all the referenced schema files except signatures.xsd and do not need to be specified in the instance document. The prefix and schema location attributes for signatures.xsd need to be specified in the instance document, if the latter includes signatures information. 

OSRT is the prefix for the namespace xmlns:OSRT defining operating system resource types. Other namespaces are defined in the resourceTypes.xsd schema file. One or more of these namespaces may need to be added if the topology includes target resources of the corresponding type.

Schema diagrams are included in the following sections to support the description of elements defined in a schema type. These diagrams only show XML schema elements; they do not include a graphical representation of XML schema attributes. The latter are described in the text. The following graphical conventions are used in these diagrams:

• A solid line border indicates a required element (minOccurs=”1”)
• A dotted line border indicates an optional element (minOccurs=”0”)
• Multiple rectangles beneath an element’s name indicate that there may be multiple occurrences. In that case, there is a label showing the multiplicity.
• A small square with an inner “+” symbol at the right end of a rectangle indicates that the corresponding element is an instance of a complex type (not expanded).
• A connector with horizontally aligned dots indicates a sequence content model.
• A switch connector with vertically aligned dots indicates a choice content model. 

5.1 Installable Unit Identity

The identity element is required for any installable unit. The element is an instance of base:IUIdentity, which is illustrated by the following diagram.

 

 

·        UUID [type=base:UUID]
UUID is a REQUIRED element. A unique identifier for the IU type is provided by the union of the UUID and version values.

The UUID type is defined to be compatible with existing standards dictating the generation and string representation of universal identifiers. The schema required representation of the UUID is by a hexBinary XML type of length=16-octets (32 chars). Two categories of generation algorithms have been considered, which both generate a 16-byte binary UUID. The first category includes the ISO compliant algorithms based on the use of IEEE 802 identifiers (MAC address) for the “space” part, e.g. the DCE-RPC UUID generator. The second category includes algorithms that make no use of the MAC address.

Note: the hyphenated string version of the UUID specified by the ISO standard cannot be used as a value of the base:UUID type. The value must be obtained as the 16-octects hexadecimal representation of the binary value (no hyphenation).

·        name  [type=token]
This is a REQUIRED element: both name and UUID MUST be specified.  The value is an internal, not language sensitive name of the software component represented by the IU. A name is needed for the following non exclusive uses:

·        Some implementations of a hosting environment[3] MAY NOT support UUIDs. However, since both name and UUID are always available it is not necessary to use multiple IU definitions to deploy the same IU on different hosting environments.

·        The IU MAY be installed on a system and be registered in a legacy registry of installed software by some printable name. This element could specify the same printable name in the IU XML descriptor, thus making it possible to identify an instance found in the legacy registry as an instance of the same IU.

·        A system providing life-cycle management of installable unit descriptors, e.g. an IUDD library system, needs to provide means by which an installable unit can be referred to by a user-friendly name. As an example: when creating a new version of an existing installable unit, a developer may need to retrieve the UUID of the base version. The base application can be retrieved by searching the library system with the user-friendly name.

·        One may need to search for different products that have different UUID yet are all members of a product family. For example, assuming “MyProduct” version 10 does not declare backward compatibility with “MyProduct” version 3 the two MAY have different UUID values (see 5.1.1 below) . A management application may need to locate all instances of  “MyProduct”, regardless of version. This can be achieved by a name search if the name of both versions contains a common  sub-string.

·        displayName [type=base:DisplayElement]
This OPTIONAL element associates text labels and a description with the corresponding IU. See Section 17 for a general description of display elements and their localization.

·        manufacturer [type=base:DisplayElement]
This OPTIONAL element specifies the name and description of the IU manufacturer. See Section 17 for a general description of display elements and their localization.

·        buildID [type=token]
This OPTIONAL element is provided to allow a correlation to a build identifier used in a vendor-specific build process.

·        buildDate [type=dateTime]
This OPTIONAL element contains the build date for the installable unit.

·        version [type=vsn:VersionString]
This  element defines the IU version. The version value is a string composed of up to four parts, according to a Version.Release.Modification.Level (V.R.M.L) scheme. The first  and second parts are required (Version.Release). XML types used in this specifications for version data are defined in Appendix H.  

·        backward_compatibility [anonymous type – sequence of vsn:VersionString]
This element defines a sequence of version elements, each one for a previous version of the same component, that the current one declares to be backward compatible with. These previous versions relate to the same UUID: it is not possible to specify backwards compatibility to a different UUID. Backwards compatibility implies that any dependency on version “X” of component “B” stated by a component “A” CAN be satisfied by a version “Y” of component “B” that exists in the system if version “Y” is declared to be backward compatible with version “X”.

At least the first two parts of the version MUST be specified in each of these elements. When some of the trailing version parts in the value of one of these elements are omitted, the IU being defined is assumed to be backward compatible with any possible version matching the parts which are specified.

·        full [anonymous type]
The presence of this element indicates that the IU can be used for creating a new instance. The OPTIONAL specification of a upgrade base indicates that it can be used also as an update to an existing IU instance. See Section 11.

·        incremental [anonymous type]
The presence of this element indicates that the IU can only be used as an update to an existing IU instance. See Section 11.

 

5.1.1           Rules for assigning the UUID

A new version of an existing installable unit that maintains compatibility to a previous version and that is eligible to satisfy dependencies originally stated for that previous version MUST have the same UUID. In that case, the backward_compatibility element of the IU identity is used to formally declare the backward compatibility with one or more previous versions. 

An installable unit that does not retain full backward compatibility with a previous version, MUST still retain the same UUID of a previous level if it can install as a full or incremental update on top of that level.

A new UUID SHOULD be created when the component is first created or in case the component is broken apart and pieces used to reconstruct something different.

A new UUID MAY be also created for a new version which breaks backward compatibility with and cannot be installed as an upgrade to the previous version.

5.1.2           IU Identity Example

The following XML fragment illustrates the elements of IU identity.

 

<identity>

<name>Human readable name, possibly used in a native registry</name>

<UUID>12345678901234567890123456789012</UUID>

<displayName>

        <defaultLineText key="ST_01">Line text about package</defaultLineText>

        <defaultText key="LT_01"> Paragraph text about package</defaultText>

</displayName>

<manufacturer>

        <defaultLineText key="ST_02">ACME Software</defaultLineText>

        <defaultText key="LT_02">The true ACME Software</defaultText>

</manufacturer>

<buildID>1234XYZ</buildID>

<buildDate>2001-12-31T12:00:00</buildDate>

<version>1.1</version>

<backward_compatibility>

        <version>1.0</version>

</backward_compatibility>

</identity>

5.2 Temporary Fix Identity

A temporary fix is an installable unit that is not part of the normal sequence of released versions, although it has a definition similar to that of an ordinary IU. In particular, the identity of a fix is defined by the base:FixIdentity type, illustrated by the following diagram. This type and base:IUIdentity are both derived types of base:BaseIUIdentity. Therefore, a fix repeats the definition of the following elements described in the previous section (the name and UUID elements identify the installable unit to which the fix is intended to be applied)

·        name

·        UUID

·        displayName

·        manufacturer

·        buildID

·        buildDate

 

Additional elements of the fix identity are described below.

·        incremental/requiredBase [type=base:RequiredBase]
This is a REQUIRED element specifying the range of versions (minVersion and maxVersion elements, both instances of vsn:VersionString) to which this fix can be applied.

·        fixName [type=NCName]
This is a REQUIRED element specifying the fix name. This name MUST be unique among all fixes that apply to installable units with the specified UUID.

·        fixType [anonymous type]
This is an OPTIONAL element, used to categorize the fix. See Section 9.2.

·        fixDependencies [anonymous type]
This is an OPTIONAL element, used to express dependencies (pre-requisites, co-requisites and ex-requisites) among fixes that could be applied to the same IU instance. This element can only be specified for an IU deployed to a single target (SIU or CIU). See Section 9.2.  

 

5.3 Root Installable Unit

A root installable unit describes a complete “unit of manufacture”, as shipped by the installable unit developer. There is exactly one root IU in an installable unit descriptor.

A root installable unit is a derived type of iudd:AggregatedInstallableUnit, which in turn is a derived type of siu:InstallableUnit. The relationships between these two types are illustrated in the following diagram.

The base type – siu:InstallableUnit – includes a definition of the IU via the group siu:IUorFixDefinition – this can select different contents depending on whether this is an ordinary IU of a temporary fix – and the group base:Variables. A key element in the first group is the IU identity whose elements are described in sections 5.1 and 5.2. Other elements of an IU definition are covered in Section 9 (Software Smallest Installable Unit). Variables are covered in section 8 (Variables, Expressions and Conditions).

The AggregatedInstallableUnit type defines the base content of the root IU, as a set of installableUnit elements. Each element is an instance of type iudd:ConditionedIU,  described in Section 6, and may represent any of the following:

·        An inline IU aggregate, i.e. a Solution Module (SM) or Container Installable Unit (CIU), respectively described in Sections 6.1 and 6.4.

·        An inline leaf node, i.e. a Smallest Installable Unit (SIU) or a Configuration Unit (CU), respectively described in Sections 9 and 10.

·        A bundled referenced IU, described in Section 6.2.

·        A federated IU, described in Section 6.3.

The other top-level elements of the RootIU type are illustrated in the following diagram.

 

A root installable unit has the following attributes:

·        IUName [type=ID]
A REQUIRED IUName, which uniquely identifies the IU within the scope of the descriptor. The value MUST be unique within the descriptor.

·        targetRef [type=IDREF]
An OPTIONAL targetRef attribute which if specified MUST refer to one of the targets defined in the topology. When specified, this attribute implies that all installable units defined within this root IU MUST be deployed onto the same target. Consistently with this declaration, all the installable units that are part of the the root IU MUST specify the same target.

·        language_bundle [type=token]
An OPTIONAL attribute which has a default value of “iudd_bundle”. This is used for the localization of display elements. See Section 17.

A root installable unit has the following elements:

·        selectableContent [anonymous type]
This element defines the selectable content of the root IU as a set of installableUnit elements. These are instances of iudd:ConditionedIU. The inclusion of installable units defined as part of the base content is determined by the associated condition. The inclusion of installable units defined by this element is also dependent on the selection of features. See Section 5.4.

·        features [anonymous type]
The set of features that may be selected. See Section 5.4.

·        rootInfo [anonymous type]
The rootInfo element, which describes the product or offering contained in the root IU. See Section 5.5.

·        customCheckDefinitions [anonymous type]
The set of custom checks that is used within the root IU and its embedded (inline) installable units. Custom checks use artifacts that can be executed on a target (e.g. an operating system) to check dependencies that are not defined in this schema. See Section 7.3.8.

·        topology [anonymous type]
The target topology onto which the installable unit is to be deployed. The target topology consists of a set of target definitions, covering both targets that must be there before the root IU can be installed, and targets that may be installed as part of the install of the root IU. See Section 5.6.

·        groups [anonymous type]
The installation groups that the product or offering supports, and the default installation group that should be selected if no other selection is made. An installation group defines a set of features that should be installed together. See Section 5.4.

·        requisites [anonymous type]
The bundled requisite IUs that are shipped with the root IU. These are referenced IUs that may be used to satisfy unmet dependencies. See Section 5.7.

·        files [anonymous type]
The set of files that comprise the root IU. These files are given a file ID by which they can be referenced within the root IU and are subject to integrity checks. Each file ID MUST be unique within the root IU. See Section 5.8.

5.4 Features and Installation Groups

Features provide the means for external (e.g. user) selection of the installable units within the root IU. This is in contrast to conditions, which filter what is installed based on environmental properties.

Installation groups provide a means of specifying recommended selections of features, for example tailored to a particular use, user role or resource constraints. An example of a set of installation groups might be “Custom”, “Typical” and “Full”. An installation group specifies which features the user is able to select from, and which features are selected by default. Optionally, a default installation group can be specified.

Features may be specified as the target of dependency checks. They are identified by a feature name that is unique within the root IU.

 

Features

Selectable content

The diagram above illustrates how features are used. The root IU contains IUs, which are partitioned into base content (always installed) and those IUs that are selectable via features. Features contain subfeatures and/or selectable content. The selectable content can be shared between multiple features, but subfeatures are not shared. The features must select the top-level of the content: they cannot arbitrarily select subtrees.

Referenced IUs also contain features, and the aggregating IU needs to specify what features within these referenced IUs should be selected. There are two mechanisms for doing this. First, the referenced IU definition may specify an installation group and may also specify explicit selections within the referenced IU. This will establish the features in the referenced IU that are to be installed when that referenced IU is selected. Second, individual features may federate features within a referenced IU. This will cause the selection of that feature if it is not already selected. Further, it will associate the lifecycle of the referenced feature with the feature federating it, so that if the federating feature is uninstalled and the referenced feature is no longer used, it may also be uninstalled.

The selection of features is controlled as follows:

·        As previously identified, what the user can select and the default selections are set via installation groups.

·        Some features are identified as “required”. These features are always selected if their parent is selected (a top-level required feature is always selected).

·        Features may identify the following selection constraints on other features:

o       Select if selected

o       Deselect if selected

o       Select if deselected

o       Deselect if deselected

·        Referenced features may express a set of “ifreq” relationships to other features. The referenced feature is only selected if at least one of its “ifreqs” is satisfied. If an “ifreq” is subsequently installed, any features previously selected but not installed because of the “ifreq” should now be installed.

The following illustrates how features and installation groups may be used, e.g. during an interactive install.

If the root IU defines installation groups, the user is presented with the set of installation groups to choose from. If a default installation group is specified, this indicates the initial selection that should be presented. If no installation group is defined, the user may select from any of the features.

Each defined installation group indicates the set of default feature selections, and indicates whether the user can change the selection. 

Within an install group, a feature’s selection can be specified as “not changeable”. This means that the selection state of the feature is determined entirely by internal selection rules, and not by user selection. In this case a user should not be allowed to change the feature’s selection state.

The user selects a single install group, and then makes selections from the offered features.

When the user had made their selections, the install program will determine which IUs are to be installed. This will consist of the base content, plus all IUs that are federated by the selected features, plus the IUs that are selected in referenced IUs through the referenced IU definition (see below) or through feature references. These IUs are then filtered based on any conditions: only IUs with no condition or a condition that evaluates to true will be installed.

The features to be selected in referenced IUs are determined as follows:

·        An explicit install group can be specified. If so, this install group specifies the default selections.

·        If no explicit install group is specified, the default install group specifies the default selections.

·        If no explicit or default install group is specified, no features are selected for the referenced IU (unless referenced feature definitions are specified in the root IU, see below).

·        Further explicit feature selections can be specified in the referenced IU definition. These are in addition to the selections in the install group. They are not subject to any constraints specified in the install group.

Features selected by feature references are then selected in addition to the selections specified in the referenced IU definition.

Feature selection is illustrated in the example in Section C.

Install group and features selections determine the set of IU that are being installed, but not the order in which these are installed, which is determined by the IU hierarchy, sequence numbers and intra-IU dependencies.

Install group selections and feature selection rules are provided for use by install programs and their implementation is OPTIONAL. It is the responsibility of those components to determine the appropriate behavior if the constraints are violated (e.g. ignore, warn, error).

5.4.1           Feature

A feature definition includes the following attributes:

·        featureID [type=ID]
This REQUIRED attribute provides a unique identifier to reference the  feature definition within the root IU. The value MUST be unique within the descriptor.

·        required [type=boolean]
If this OPTIONAL attribute is true, then the feature is always selected if it is either a top-level feature, or if its parent feature is selected.

·        type [type=iudd:FeatureType]
The type of this OPTIONAL attribute is defined as a union of the XML type NCName and iudd:StandardFeatureType. Therefore, a user defined feature type can be specified as an NCName value. “Documentation”, “Language” and “Samples” are the standard enumerated values defined in  iudd:StandardFeatureType.

A feature definition includes the elements illustrated in the following diagram.

 

 

·        identity [anonymous type]
This is an instance of a type containing the following elements

o       name [type=token]
This is a name by which the feature can be registered, and by which it is possible to reference the feature from an external descriptor. The value MUST be unique among features defined within the same root IU.

o       displayName [type=base:DisplayElement]
This OPTIONAL element may be used to associate a language sensitive name and description to the feature. See Section 17.

·        feature [type=iudd:Feature]
Zero or more feature elements can be specified, each one describing a child feature. The parent-child relationship between two features implies that children SHOULD NOT be selected when their parent is selected. 

·        IUNameRef [type=IDREF]
Zero or more IUNameRef elements, each one selecting a top-level IU defined as part of the root IU selectable content.

·        referencedFeature [type=iudd:ReferencedFeature]
Zero or more referencedFeature elements, each one referencing a feature within a referenced IU. See Section 5.4.2.

·        selectionRules [type=anonymous]
Zero or more selection rules. Each selection rule identifies the feature name of a different feature within the root IU, which is the subject of the rule. The possible rules are:

o       SelectIfSelected [type=IDREF]
The specified feature is selected if this feature is selected.

o       DeselectIfSelected [type=IDREF]
The specified feature is deselected if this feature is selected.

o       SelectIfDeselected [type=IDREF]
The specified feature is selected if this feature is deselected.

o       DeselectIfDeselected [type=IDREF]
The specified feature is deselected if this feature is deselected.

5.4.2           Referenced Features

A referenced feature is illustrated in the diagram below:

A “referenced feature” defines a selection of a feature in a referenced IU or in a federated IU. A referenced feature has the following elements:

·        IUNameRef [type=IDREF]
This REQUIRED element is the identifier of the referenced or federated IU that the feature is in. See Section 6.2  for a definition of referenced IUs, and Section 6.3 for a definition of federated IUs.

·        externalName [type=token]
The value of this REQUIRED element MUST match the name of the feature, within the referenced IU descriptor, that needs to be selected. When the feature is associated to a federated IU, any IU check in the federated IU definition MUST identify an IU that has a feature with the specified name.

·        ifReq [type=anonymous]
This OPTIONAL element can be used to specify one or more featureIDRef elements. These are references of the IDREF type to features defined within the same root IU of the feature being defined. The selection of any of the specified features in the root IU causes the selection of the feature in the referenced IU. See Appendix C for an example. 

A referenced feature can only refer to a contained referenced IU or a  federated IU that is part of the base or of the selectable content. A referenced feature CANNOT refer to a requisite IU.

5.4.3           Scoping of Features

The following rules apply to feature scope and override.

·        Features are defined in the root IU. The featureID must be unique within the descriptor.

·        Referenced IUs have a separate namespace for features. The only interaction is via the specification of the selection of a feature within a referenced IU or referenced feature.

5.4.4           Installation Groups

An installation group is defined by the iudd:InstallationGroup type. A group defines a set of features that should be installed if the group is selected.

A group definition includes the elements illustrated in the above diagram.

·        groupName [type=token]
This REQUIRED element is the name of the group. The value MUST be unique within the descriptor.

·        feature [anonymous type]
A list of the feature selections that are to be made as part of the installation group. A feature selection element consists of the following attributes:

o       featureIDRef [type=IDREF]
This must be a valid reference to a feature within the root IU.

o       selection [type=iudd:Selection]
This is an enumerated type whose possible values are “selected” and “not_selected”. This specifies whether the feature is to be selected or not selected by default. The default value is “selected”.

o       selectionChangeable [type=boolean]
This element provides an indication of whether the selection is externally changeable (e.g. by the user or automated install program). If this indication is “false”, then the feature’s selection is only changed in response to internal selection rules. The default value is “true”.

·        description [type=base:DisplayElement]
This is an OPTIONAL human-readable description. See Section 17.

A feature may be a member of multiple groups, or of no groups.

Groups cannot contain other groups.

The use of installation groups is illustrated in the example in Appendix C.

5.4.5           Scoping of Installation Groups

The following rules apply to installation group scope.

·        Groups are defined in the root IU. The value of the groupName element must be unique within the descriptor.

·        Each referenced IU has a separate namespace for installation groups. The only interaction is via the specification of the selection of an install group within a referenced IU.

 

The following UML class diagram illustrates features and installation groups.

 

 

5.5 Root IU Information

The information included by the rootInfo element  are illustrated in the following diagram.

The rootInfo element is a container for the following elements

·        schemaVersion [type=vsn:VersionString]
This REQUIRED element identifies the version of the schema being used.

·        build [type=nonNegativeInteger]
This REQUIRED element is the root IU build number. This identifies the version of the descriptor separately from the version of installable units that the descriptor contains. A newer (better) descriptor may be the result of replacing the implementation of a custom check (external command), or of identifying a previously unrecognized dependency, or of relaxing a previous dependency because testing has now validated a wider range of valid environments. The IU developer is responsible for the decision as to whether the changes should affect the versioning of an installable unit.

·        size [type=integer]
This OPTIONAL element defines the size of the root IU, in Kilo-bytes (1K=1024). The value indicates the amount of disk space required to store the whole root IU including all descriptors, files and referenced IUs, in an unpackaged form.

·        bigIcon [anonymous type]
This OPTIONAL element has a REQUIRED attribute – fileIdRef – of IDREF type. This is a reference to a GIF file containing a 32x32 icon associated with the root IU.

·        smallIcon [anonymous type]
This OPTIONAL element has a REQUIRED attribute – fileIdRef – of IDREF type. This is a reference to a GIF file containing a 16x16 icon associated with the root IU.

·        type [type=NCName]
This OPTIONAL element can be used to categorize the root IU. One among the following enumerated values can be specified for this element, to support a componentization strategy:

o       Offering

o       Assembly

o       CommonComponent

5.6 Target Topology

The topology definition consists of a set of one or more targets and an OPTIONAL set of deployed targets. Both types define some manageable resource that play a role in the solution being deployed. In particular, deployed targets define resources that are created as a result of deploying the solution.

 

Targets are described in Section 5.6.1. Deployed targets are described in Section 5.6.4.

5.6.1            Target

A target defines a manageable resource that plays a role in the solution. A target definition MAY be referenced within installable units because

·        it represents the installable unit’s hosting environment, or

·        it is the target of a property query associated to a variable definition, or

·        it is the target on which a check must be performed, or

·        it is one end of a binary relationship that must exist between two resources.

The target element is an instance of the iudd:Target type, illustrated in the following diagram.

 

A target definition is used to identify one or more instances of a given resource type based on scope, selection requirements and validation requirements. A target definition has the following attributes:

·        id [type=ID]
This REQUIRED attribute is used as an identifier for the target. References to a target MAY be made from within the same root IU descriptor or they MAY be made in a target map within another root IU which the current one is contained (or federated) by. Targets MUST NOT be referenced from referenced installable units: a target map MAY be used to correlate between targets in different root IUs. See 5.6.3 for a description of target maps.

·        type [type=iudd:AnyResourceType]
This REQUIRED attribute is used to specify the target resource type, e.g. an operating system type, or a J2EE application server type. The type of this attribute is defined as a union of the XML type QName and rtype:RType. Therefore, a user defined resource type is specified as a QName value. Standard enumerated values for this field are defined in rtype:Rtype.

A target definition has the following elements:

·        description [type=base:DisplayElement]
This OPTIONAL element allows to associate text labels and a description with the target. See Section 17 for a general description of display elements and their localization.

·        scope [anonymous type]
This REQUIRED element identifies how to resolve the target instances among the ones satisfying the selection requirements (dependencies and relationships). One of the following values can be specified (the default target scope value is one):

o       one –  the target set MUST be resolved to a single instance;

o       all –  the target set MUST include every selected instance;

o       some –  the target set MUST include one or more selected instances.

If scope is one or some and there is more than one match, the deployment application MAY apply some pre-defined policy, select from matching targets based on validation dependencies or interact with the user to make the selection.

·        members [anonymous type]
This OPTIONAL element may be used to set the initial selection of targets from the union of two or more other targets. The element includes one or more member elements:

o       member [type=IDREF]
One or more member elements must be specified if the members element is present. Each element is a reference to a target that is part of the union being defined.

If any member elements are present, then the selection dependencies apply only to the union of the referenced target sets; the final target set SHALL not include any additional targets (not part of the union) that might match the selection dependencies. Referenced targets MUST be defined within the same root IU.

Targets with members are useful when there are platform specific components in the root IU and components that are platform independent.  As an example, the root IU may include versions of a platform specific language interpreter for two different operating systems, each one of the latter being represented by a topology target. The root IU may also include an installable unit for scripts that should be installed on instances of both operating systems, on which the scripts can be run using the language interpreter. The platform independent IU containing the scripts could be conveniently associated to a new target which defines each of the operating system targets as a member target.

·        checks [type=siu:CheckSequence]
The set of checks that SHOULD be performed on this target, and made available for use in requirements specified on the target and within any inline IU within the root IU. See Section 7.1 for a definition of checks.

·        selectionRequirements [anonymous type]
This OPTIONAL element is used to specify the set of selection requirements that SHOULD be used to select resource instances in this target set. Requirements are described in Section 7.2.

Selection requirements and the target scope attribute (one, some orall) determine the set of instances, for a logical target, that are expected to play the target’s role in the solution. Examples: one instance of an operating system with client runtime code installed to access a database; or all J2EE application servers that are federated by a cluster resource. A target scope of some implies that one or more instances MUST be selected among the ones that satisfy the selection requirements. When selection requirements are omitted, the set of potential target instances is determined by the target type and scope attributes.

Not all targets defined in the topology need to be resolved. As an example, a target “T” may only be referenced as the hosting environment of one feature that is not selected. An implementation SHOULD be able to deploy the solution successfully even if there are no instances satisfying the selection requirements for target “T”. In general, an implementation SHOULD only validate selection requirements for a target that

o       is the hosting environment of at least one IU in the base content, OR

o       is the hosting environment of at least one selected feature, OR

o       is referenced by checks (see Section 7.1) defined by one base IU or by a selected feature, OR

o       is related (transitively) by relationship checks to one or more targets satisfying the previous criteria.

In particular, one or more member targets of a target “U” may be not resolved according to the above criteria. However, there MUST be at least one member target resolved if the target “U” itself needs to be resolved.

·        validationRequirements [anonymous type]
This OPTIONAL element is used to specify the set of validation requirements that SHOULD be met by any target instance that have been selected in this target set, in order for the instance to function in the target’s role within the solution. Requirements are described in Section 7.2.

A requirement MAY provide information that is needed to modify the target so that the requirement can be met. Validation requirements MAY be used to assist in further selection from the target set if the scope is one or some.

Declaring a requirement in the validation group has a different effect than declaring the same requirement in the selection group. In particular the following conditions for install failure are determined by the target’s scope and requirements:

o       Scope= “one”
Solution install fails if the selected target instance fails to meet a validation requirement.

o       Scope= “all”
Solution install fails if any selected target instance fails to meet a validation requirement.

o       Scope= “some”
Install fails on any selected target instance that fails to meet a validation requirement. However, the solution can be successfully installed if at least one target instance meets the requirements.

·        targetMap [type=iudd:TargetMap]
This OPTIONAL element defines a correspondence between this target and targets defined within referenced IUs. See Section 5.6.3.

5.6.2           Scoping of Targets

The following rules apply to the visibility of target definitions:

·        Targets and deployed targets are defined in the topology of the root IU and are available to be referenced by any IU in the package: each one of the targets and deployed targets that are referenced within an IU MUST be declared in the root IU topology.

·        Targets and deployed targets MUST have a unique identifier (id) within the descriptor.

·        Referenced IUs have a separate namespace for targets. The only interaction is via target maps.

5.6.3           Target Maps

Target maps provide a mechanism to map topology in the top-level root IU to targets into the topology of referenced IUs. A referenced IU MAY contain targets that are not contained in the aggregating root IU, and vice versa.

A selected target SHOULD satisfy the requirements specified in the topology, plus the requirements specified in any selected referenced IU for which a target map to the selected target has been specified. This applies recursively to any referenced IUs within the referenced IU.

The target map is defined within a given target element using the iudd:TargetMap type. The targetMap element has the following attribute:

·        IUNameRef [type=IDREF]
This REQUIRED attribute type identifies the referenced IU, within the descriptor, that the map refers to.

A target map includes one or more instances of the following element:

·        externalName [type=NCName]
The value of this element must be identical to the target identifier used in that referencedIU for the mapped target.

The following shows an example of using target maps. In this example, the containing root IU has a topology with only a single target (a J2EE application server). The root IU references two other root IUs (SM1 and SM2), which also have a target of the same type (J2EE Application Server) but which have used different names to refer to that target. When this root IU is deployed, the three targets tSvr, AppServer (in SM1) and tServer (in SM2) SHOULD all resolve to the same physical target.

<topology>

   <target id="tSvr" type="J2EE Application Server">

      <scope>one</scope>

      <targetMap IUNameRef="SM1">

         <externalName>AppServer</externalName>

      </targetMap>

      <targetMap IUNameRef="SM2">

         <externalName>tServer</externalName>

      </targetMap>

   </target>

</topology>

 

       

5.6.4           Deployed Target

The topology may include the definition of resources, including target hosting environments, that are created during the deployment of the IU, and do not already exist prior to deployment. This allows an IU to be targeted at a hosting environment that has not yet been created. In general, deployed targets are manageable resources that play a role in the solution and that MAY need to be configured using Configuration Units (CU). 

 

Figure 7: Example of a deployed target – initial deployment

In the above diagram, a solution module (SM) consists of an SIU that deploys a hosting environment (J2EE Server), and then deploys a J2EE application into that server. The first step is to specify the initial required topology, which consists of a Linux operating system, and a relational database. The J2EE Server is to be installed into the operating system.

The second step is to specify the deployed topology which will be created by the first SIU, and into which the J2EE application will be deployed. The deployed target definition associates the J2EE server target with the SIU that instantiates the resource.

Figure 8: Example of a deployed target – deploying into the deployed target

Each deployed target definition is an instance of the iudd:DeployedTarget type. This type is illustrated in the following diagram.

A deployed target definition has the following attributes:

·        id [type=ID]
This REQUIRED attribute is used as an identifier for the target.

·        type [type=iudd:AnyResourceType]
This REQUIRED attribute is used to specify the target resource type.

A deployed target definition has the following elements:

·        description [type=base:DisplayElement]
This OPTIONAL element allows to associate text labels and a description with the target. See Section 17 for a general description of display elements and their localization.

EITHER (element of a CHOICE)

·        IUNameRef [type=IDREF]
The value of this element is a reference to the IU within the root IU that will deploy the target resource. The value MUST refer to the IUName identifier of an IU specified within the base or selectable contents of the root IU.

OR (element of a schema CHOICE )

·        targetMap [type=iudd:TargetMap]
This element maps the target  to a corresponding deployed target in a referenced IU. Target maps are described in Section 5.6.3.

5.7 Bundled requisite IUs

The requisites element of the root IU identifies bundled requisites that are distributed with the root IU. Bundled requisite IUs are a form of Referenced IUs, see Section 6.2. Note that bundled requisites need to have targeting information, so that it is known where to install the individual SIUs. This means target maps need to be provided in the topology section, for the bundled requisites as well as the aggregated referenced IUs.

Figure 9: Federated and bundled requisite IUs

 

Figure 9 illustrates a bundled requisite IU, IU “C”, which may be used to satisfy the dependency expressed by IU “A.2”.

A bundled requisite IU can be used to create an instance satisfying the requirement of a contained IU (inline or referenced) or it can be used to create an instance of a federated IU.

In the first case, the bundled requisite IU is referenced via the canBeSatisfiedBy element in a software check or in an IU check within the contained IU. The created instance of the bundled requisite IU MAY be deleted, if it is not shared by other IUs, when the contained IU depending on that instance is deleted.

In the second case, the bundled requisite IU is used to create an instance of the federated IU, if one is NOT found. The created instance of the federated IU is meant to be a shared component and SHOULD NOT be deleted before all parent IUs are deleted. 

In general, sharing of an IU MAY be limited by specifying the maximumSharing identity constraint in its definition. See Section 9.1.

5.8 Files

The descriptor contains a definition for each file that needs to be available during deployment together with the root IU descriptor. Files in the following categories MUST be defined in this section of the root IU descriptor:

·        A file containing the IU deployment descriptor (XML document) of a referenced (or requisite) IU.

·        A file containing an artifact (descriptor) referenced in an SIU or CU definition. See Sections 9.3 and 10.1 for a description of artifacts.

·        A file referenced within any of the above artifacts.

Multiple file elements can be specified within the files section. These are instances of the iudd:File type, illustrated in the following diagram.

 

A file element definition has the following attributes:

·        id [type=ID]
This REQUIRED attribute is used as a key to reference the file element from other types. The value MUST be unique within the descriptor.

·        compression [type=boolean]
An OPTIONAL attribute  specifying whether the file needs to be automatically compressed during packaging and automatically decompressed before use by actions (default is “true”).

·        charEncoding [type=base:CharacterEncoding]
This is an OPTIONAL attribute. When specified it indicates that the file contains text in the specified encoding. The code is identified by the IANA character set name (http://www.iana.org/assignments/character-sets).

A file element definition has the following elements:

·        pathname [type=base:RelativePath]
This REQUIRED element provides the relative path of the file image relative to a logical source as specified in the IU Package Format specification (see [IUPACK]). This logical source is the same for all files defined in the root IU.

·        length [type=integer]
A REQUIRED element specifying the length of the file image as included in the root IU, in bytes. If the file compression attribute is specified, this is the length of the compressed image.

·        checksum [type=base:CheckSum]
A REQUIRED element specifying the checksum of the file image as included in the root IU. If the file compression attribute is specified, this is the checksum calculated on the compressed image

 

6                  Installable Units

Installable units can be aggregated in a tree-like hierarchy whose leaf nodes are Smallest Installable Units (SIU) and Configuration Units (CU). The following three aggregate types can be defined for installable units:

• Root Installable Unit
  This the top-level aggregate. As described in the previous section, the IUDD defines a single root IU.
• Solution Module (SM)
  This IU aggregate type is the most general that can be defined within a root IU, because installable units contained in the solution module can be associated to different topology targets. Solution modules are defined in Section 6.1.
• Container Installable Unit (CIU)

This IU aggregate type contains installable units that are associated to the same topology target. The whole CIU is deployed onto each instance of the target. Container Installable Units are defined in Section 6.4.

An independently packaged root IU may be aggregated within another root IU by a reference made in the aggregating root IU to the bundle file containing its deployment descriptor (IUDD). An independently packaged root IU is referred to in this specification as a referenced IU. Referenced IUs are described in Section 6.2.

A root IU may be shared by one or more root IUs, in which case it is referred to as a federated IU. This relationship is declared in the federating root IU by means of installable unit checks. Federated IUs are defined in Section 6.3.

The following restriction MUST be satisfied by all of the IU aggregates defined in this specification:

An IU aggregate MUST NOT have two children with the same UUID.

See Section 12.5.1 for a motivation of the above restriction.

6.1Solution Module

 

A solution module is a type of aggregated installable unit, as described in Section 5.3. Specifically, it is a multi-target installable unit, and therefore SHOULD NOT specify a target reference. The structure of a solution module is illustrated in the above diagram.

 

Each installableUnit element contained in a solution module is an instance of the type iudd:ConditionedIU, illustrated in the following diagram.

 

These installable units are either targeted at a single hosting environment (SIU, CIU, containedCIU, federatedCIU, configurationUnit), or at multiple hosting environments (solutionModule, containedIU, federatedIU).

The installableUnit element [type=iudd:ConditionedIU] has the following attributes:

·        targetRef [type=IDREF]
This is an OPTIONAL attribute. If specified the value MUST refer to one of the targets defined in the topology, see Section 5.6. The targetRef MUST be specified if the aggregating IU is a multi-target IU and the conditioned IU is a single-target IU (e.g. a CIU or a referenced IU with a targetRef attribute on the root IU). If the aggregating IU is a single-target IU then the targetRef attribute MAY NOT be specified: if it is specified, it MUST have the same value as the aggregating IU’s target.

·        condition [type=base:VariableExpression]
This is an OPTIONAL variable expression representing a condition. The latter determines whether the installable unit should be installed. The default is “true”. See Section 8.3 for a description and syntax of conditional expressions.

·        sequenceNumber [type=nonNegativeInteger]
This OPTIONAL attribute can be used to control the order of install. See Section 12.4.

Each installableUnit element [type=iuddConditionedIU] includes one (XML schema choice) among the following elements:

·        SIU [type=siu:SmallestInstallableUnit]
See Section 9.

·        CIU [type=iudd:ContainerInstallableUnit]
See Section 6.4.

·        containedCIU [type=iudd:ReferencedIU]
This is a single-target referenced IU. See Section 6.2.

·        federatedCIU [type=iudd:FederatedIU]
This is a single-target federated IU. See Section 6.3.

·        configurationUnit [type=siu:ConfigurationUnit]
This element defines a configuration unit. See Section 10.

·        solutionModule [type=iudd:SolutionModule]
This is a nested solution module definition.

·        containedIU [type=iudd:ReferencedIU]
This is a multi-target referenced IU. See Section 6.2.

·        federatedIU [type=iudd:FederatedIU]
This is a multi-target federated IU. See Section 6.3.

6.2 Referenced IU

A referenced IU is defined by an instance of iudd:ReferencedIU, the type illustrated in the above diagram.

A referenced installable unit has the following attribute:

·        IUName [type=ID]
This is a REQUIRED attribute by which the installable unit MAY be referenced within the root IU. The value MUST be unique within the descriptor.

A referenced installable unit has the following elements:

·        fileIdRef [type=IDREF]
This element is REQUIRED. The value is a reference to the file that contains the descriptor for the referenced installable unit.

·        parameterMaps [type=base:Maps]
This is an OPTIONAL element, defining a set of parameter maps. See Section 6.2.1 for a definition of parameter maps.

·        featureSelections [anonymous type]
This is an OPTIONAL element, defining a set of feature selections. It consists of the following elements:

o       externalInstallGroup [type=token]
This element is OPTIONAL. The value SHOULD match the name of an install group in the referenced IU. If specified, this install group specifies the initial selections for features within the referenced IU. Otherwise, the default install group for the referenced IU is used to determine initial feature selections. If no explicit or default install group is specified, no features are selected via group definitions. 

o       featureSelection [anonymous type]
Zero or more instances of this element can be specified to provide OPTIONAL further feature selections. Each selection identifies the name of the feature in the referenced IU (externalName) and whether it should be selected or not.

§         externalName [type=token]
This element is REQUIRED. The value SHOULD match the name of a feature (name  [type=token]) defined in the referenced IU.

§         selection [type=iudd:Selection]
This element is REQUIRED.  This type allows to specify one of the following enumerated values: “not_selected” and “selected”.

·        additionalRequirements [anonymous type]
This element is OPTIONAL. It may be used to specify additional requirements  consisting of solution-level checks and requirements that are to be applied in addition to any checks and requirements defined within the referenced IU, to the specified target. These MAY be used to further constrain the use of an installable unit: for example to restrict the install of a J2EE Server to use one specific database product, where the J2EE Server may be capable of using multiple database products. They MAY also be used to specify additional resource requirements: for example, if a diskspace consumption requirement of 100MB is specified within the referenced IU, and one of 50MB is specified in the solution module, the overall requirement for this IU in the context of the solution is 150MB. These additional requirements do not override checks defined in the referenced IU, so they MAY NOT be used to specify more permissive checks. One or more instances of the following target element are REQUIRED:

o       target [anonymous type]
This element has the following attribute:

§         targetRef [type=IDREF]
The targetRef of the target. This MUST correspond to the target identifier of a target or deployed target defined in the descriptor.

Each target definition has the following elements:

§         checks [type=siu:CheckSequence]
The set of checks to be performed on the target. See Section 7.1 for a definition of checks.

§         requirements [anonymous type] (sequence of siu:Requirement)
The set of requirements to be met on the target. See Section 7.2 for a definition of requirements.

6.2.1           Parameter Maps

A parameter map maps one or more variables defined within the root IU to parameter variables of a referenced installable unit. Input parameters in the referenced IU that do not have a parameter map SHOULD be initialized with their specified default value. Parameter maps MAY be used to override these default values. These maps SHOULD NOT be used to override the value of queries or derived variables. The type defining maps – base:Maps – is illustrated in the following diagram.

Each map in the set includes the following elements to map a variable in this descriptor into a parameter defined within the referenced IU:

·        internalName [type=IDREF]
This element is REQUIRED. The value SHOULD be a reference to a variable that is in scope, i.e. that is defined in a parent aggregate of the referenced IU. See Section 8.1.7 for a definition of variable scope.  

·        externalName [type=NCName]
This element is REQUIRED.  The value SHOULD match the name attribute [type=ID] of a parameter variable defined in the referenced IU. See Section 8.1.1 for a definition of parameter variables.

The type base:Maps is also used in different contexts for mapping IUDD variables to artifact variables (see Section 9.5). For this reason the map element includes an attribute – direction – that can be used (only for check artifacts) to specify the direction of the mapping (“in” or “out”). Only the default value (“in”) is appropriate for a map appearing in the context of a referenced IU definition.

6.3 Federated IU

During install, if an IU is specified inline, a new dedicated IU instance will be created (unless it is an update or fix IU). However, for a referenced IU, a decision may be taken to share an existing IU instance. Such a shared referenced IU is known as a federated IU. A federated IU is defined by a set of IU checks that identify acceptable IU instances, and a bundled requisite IU (see Section 5.7) that may be used to create a new instance if an existing IU cannot be selected.

Figure 9  illustrates the different possible relationships between contained IUs. IUA.1 and IUA.2 are inline and have HasComponent relationships (i.e. dedicated containment) with SM A. IU B is a referenced IU (i.e. it has its own root IU and a separate descriptor), and also is dedicated. However, IU E is a referenced IU which is federated, which means it may be shared by an external IU such as SM D.

A federated IU is defined by an instance of iudd:FederatedIU, the type illustrated in the following diagram.

A federated installable unit has the following attribute:

·        IUName [type=ID]
This is a REQUIRED attribute by which the installable unit MAY be referenced within the root IU. The value MUST be unique within the descriptor.

A federated installable unit defines a set of one or more alternatives:

·        alternative [anonymous type]
This element is REQUIRED. Each alternative is defined by an IU Check:

o       iu [type=base:IUCheck].
See Section 7.3.6 for a definition of IU checks. Within each IU Check, the canBeSatisfiedBy element SHOULD be specified and MUST identify the bundled requisite IU (declared within the requisites element of the root IU) that could be installed to satisfy the dependency. The IU Check SHOULD NOT specify the iuNameRef or featureIDRef elements, which are intended for specifying internal dependencies.

The reason for allowing a federated IU definition to contain multiple alternatives (IU checks) is that the required function may be provided by each member of a family of related software units that do not share the same UUID (e.g. different types of database).

Two alternatives in the same federated IU definition SHOULD NOT specify the same UUID. This restriction is necessary to support the deployment of bundled updates to federated IUs (see Section 11.4). 

Note that contained IUs (referenced or in-line) are dedicated components of their aggregating IU and SHOULD be deleted when their parent is deleted. By contrast, federated IUs are shared components and SHOULD NOT be deleted before all dependent IUs are deleted.

When a referencedFeature definition in a feature that is selected, see Section 5.4.2,  is associated to the federated IU, an IU instance MUST have the referenced feature installed to be eligible to satisfy an IU check in the federated IU definition. An implementation MAY deploy a new instance if a bundled requisite is specified via the canBeSatisfiedBy element. Some implementations MAY support installing the requested feature on an existing instance that does not have the feature installed.

 

6.4 Container Installable Unit

 

The above diagram illustrates elements that are defined in a container installable unit.

The container installable unit is a type of AggregatedInstallableUnit targeted at a single hosting environment. A definition of iudd:AggregatedInstallableUnit is provided in Section 5.3.

A CIU has the following attributes:

·        IUName [type=ID]
This is a REQUIRED attribute by which the installable unit MAY be referenced within the root IU. The value MUST be unique within the descriptor.

·        hostingEnvType [type=siu:AnyResourceType]
This OPTIONAL attribute is used to specify the resource type of the IU target hosting environment, e.g. an operating system type, or a J2EE application server type. When specified, the value of this attribute SHOULD be equal to the one specified by the type attribute of the target onto which the CIU is installed, see Section 5.6.1. The latter is identified by the targetRef attribute of the installableUnit element defining this SIU. The IU hosting environment type may be specified to exploit tooling support for the prevention of incorrect targeting. The type of this attribute is defined as a union of the XML type QName and rtype:RType. Therefore, a user defined resource type can be specified as a QName value. Standard enumerated values for this field are defined in  rtype:Rtype. When specified, the value of this attribute SHOULD be equal to the one specified by the hostingEnvType attribute of the target onto which the CIU is installed. The latter is identified by the targetRef attribute of the installableUnit element defining this CIU. by the target identified hosting environment.

Each installableUnit element in a CIU [type=iudd:ConditionedIU] includes one (XML schema choice) among the following elements:

·        SIU [type=siu:SmallestInstallableUnit]
See Section 9.

·        CIU [type=iudd:ContainerInstallableUnit]
See Section 6.4.

·        containedCIU [type=iudd:ReferencedIU]
This is a single-target referenced IU. See Section 6.2.

·        federatedCIU [type=iudd:FederatedIU]
This is a single-target federated IU. See Section 6.3.

·        configurationUnit [type=siu:ConfigurationUnit]
This element defines a configuration unit. See Section 10. 

A CIU CANNOT aggregate any of the multi-target installable unit types defined by iudd:ConditionedIU, although this restriction is not enforced in the schema.

The schema group siu:SingleTargetIUDefinition defines additional elements that are common to a CIU and an SIU, namely signatures, checks and requirements. Checks and requirements are defined in Section 7, while signatures are defined in Section 13.

Section B contains an example of a container installable unit.

7                  Dependencies

A dependency is a requirement that a certain condition involving the results of one or more elementary checks, SHOULD be satisfied by a topology resource. A software dependency is a requirement involving the result of a software check, defined in Section 7.3.5,  or the result of an installable unit check, defined in Section 7.3.6.   

The IUDD schema implements a separation between checks and requirements. The result of a check may provide information about the target resources and can be used to condition the install behavior. Requirements formally express one or more alternatives, one of which at least MUST be satisfied in order for a component to be installable, or for an instance of a target to be selected.

Checks and requirement MAY be used within the topology target definition, illustrated in Section 5.6.1, to declare the selection and validation criteria for the target.

Single-target installable unit definitions, see Section 6.4, MAY include checks and requirements defining the IU specific dependencies. These MAY be dependencies on the installable unit hosting environment target as well as any other target defined by the topology.

Requirements MAY also be defined for contained referenced IUs, see Section 6.2, in addition to those already stated in the referenced IU descriptor.

Federated IU definitions, see Section 6.3, can be also regarded as one form of software dependency.

7.1 Checks

The checks that can be performed on a single managed resource fall into several categories, each of which might imply different processing. These distinctions are made either because different syntax or semantics apply to specifying or evaluating the requirement or because greater flexibility is offered to deployment application implementers to evaluate the requirement efficiently. For example, the capacity requirements are distinguished because they require specific syntax and processing.

The IUDD supports the following check categories:

·        Capacity of the hosting environment. This specifies a property of the hosting environment, such as processor speed, which must satisfy some minimum or maximum value.

·        Consumable resource allocation of the hosting environment. This specifies resource, such as diskspace, that will be consumed by the installation. Consumption requirements are cumulative across installable units.

·        Value of named instance properties of the resource or hosting environment.

·        Version of a resource, such as the resource software version or the version of a supported standard or protocol.

·        Software requirements: the minimum and/or maximum version of software identified by its UUID or name.

·        Installable unit requirement: the installation of a given IU.

·        Relationship with another manageable resource.

·        Custom checks, involving the execution of a defined command.

The element checks is an instance of siu:CheckSequence. It can appear in a target definition (see Section 5.6.1), in a single-target IU definition (see Section 6.4) or in a referenced IU definition (see Section 6.2). The type siu:CheckSequence is defined in the following diagram.

 

Different types of check are supported:  capacity, consumption, property, version, software, iu, relationship and custom.

All checks extend the base class base:Check, which has the following two attributes that can be specified for all types of checks:

·        checkId [type=ID]
This REQUIRED attribute associates a symbolic name to the check. This name is used to refer to the result of the check in conditions and requirements. The value MUST be unique within the descriptor.

·        targetRef [type=IDREF]
This OPTIONAL attribute MAY be used to specify the target on which the check MUST be performed. If specified, the value MUST correspond to the target identifier of a target or deployed target within the descriptor.

The targetRef attribute SHOULD NOT be specified for a check within a topology target definition, or for a check within a referenced IU definition. If it is specified, it MUST identify the target in which the check definition itself is included.

If the targetRef attribute is NOT specified for a check within a CIU, SIU or federated CIU, the check is applied to the target hosting environment of the single-target IU in which it is defined.

The targetRef attribute specified for a check within a single-target IU MAY identify a target, T_R that is different from the IU target hosting environment, T_HE. In that case, either the scope of the  target T_R is “one” or there MUST be one or more relationships connecting the IU target T_HE to the check target T_R, so that it is possible to navigate these associations from any instance of T_HE to a single corresponding instance of T_R.

The following element is defined in the base class base:Check. It MAY be specified for all types of checks:

·        description [type=base:DisplayElement]
This OPTIONAL element allows to associate text labels and a description with the check. See Section 17 for a general description of display elements and their localization.

The supported checks are described in Sections 7.3 (Built-in checks) and 7.3.8 (Custom Check).  

7.1.1           Scoping of Checks

The result of a check is a boolean value, which can be referenced through the checkId attribute of the check. References to the results of a check are made in the declaration of requirements, see Section 7.2 below, and in variable expressions, see Section 8.2. In particular, a token $(<checkId>) appearing in a variable expression is expanded to the boolean value (“false” or “true”) that is the result of the check identified by the “<checkId>” value of the checkId attribute.

The following rules apply to check scope.

·        Each one of the checks that are referenced within an IU MUST be declared.

·        Check identifiers (checkId) MUST be unique within the descriptor. They MUST also be distinct from any variable name within the descriptor.

·        The scope of a check defined in an IU is that IU, and any inline IUs that the IU contains.

·        The scope of a check defined on a target is any IU that is targeted at that target. Variables definitions at the root IU level MAY reference checks defined within a topology target.

·        Referenced IUs have a separate namespace for checks.

7.2Requirements

Requirements are specified by identifying a set of combinations – alternatives – that must be met. The requirement is met when any one of these alternatives is met. Alternatives MAY have a priority indicator, so that it is possible to determine which alternative should be preferred when more that one satisfies the associated checks.

The check combination in each alternative consists of a list of the checks to be performed, which may either be specified by reference, or included in-line. All of the items in the check combination MUST be satisfied.

Each check reference SHOULD correspond to a check that is within scope, i.e. it is defined within the installable unit on which the requirement is specified; or within a parent of that installable unit; or within the target of the installable unit. It SHOULD NOT refer to a check in a sibling installable unit. 

Multiple requirements can be defined within an IU or a target definition. The following criteria determine whether a requirement should be declared in an IU or in the target where the requirement needs to be satisfied:

·        A dependency that originates from the IU should usually be declared in the IU and not in the target. This approach implies that if the IU is not selected for install, the requirement is not imposed, and a larger set of target instances is potentially eligible to install the remaining selected IUs.

·        A requirement that is not specifically associated to a software unit but is needed for the target to act its role in the solution should be declared at the target level. See 4.5.1 for a discussion of the different implications to declare a requirement for target selection versus validation.

Each requirement element is an instance of siu:Requirement, the type illustrated in the following diagram.

 

 

Each requirement defines one or more alternatives. At least one alternative MUST be satisfied for the requirement to be met. The failure to meet any requirement that is defined by an IU should cause the IU installation to fail before any action (with the exception of actions implementing custom checks) is executed, unless the install program provides some form of override policy.  Both requirements and alternatives have a description element that can be used to document the intent of the declaration.  See Section 17 for a general description of display elements and their localization.

Within each IUDefinition, requirements are specified against targets and installable units using the schema described above. Further solution-level requirements may be specified against referenced IUs, see ReferencedIU in Section 6.2.

A requirement element has the following attributes:

• name [type=ID]
  This REQUIRED attribute provides an internal identifier of the requirement.
• operations [type=base:ListOfOperations]
  This OPTIONAL attribute defines the list of lifecycle operations performed on the IU for which the requirement should be evaluated. Each item in the list MUST be one of the enumerated values defined in base:Operation, namely:
• • Create
  • Update
  • InitialConfig
  • Migrate
  • Configure
  • VerifyIU
  • VerifyConfig
  • Repair
  • Delete
  • Undo

The assumed default, if the attribute is not specified, is “Create”.

Each alternative element, within a requirement, is an instance of an anonymous type with the following attributes:

• name [type=ID]
  This REQUIRED attribute provides an internal identifier of the alternative. The value MUST be unique within the root IU.
  
  Each alternative has an associated boolean value. This boolean value  is “true” for an alternative that is selected (based on the results of the associated checks and its priority). The value is “false” for an alternative that is not selected (either because one of the associated checks is not met, or because there are other satisfied alternatives with a higher priority.
  
  References to the boolean value of an alternative can be made in variable expressions. As an example, a token $(altName) appearing in a variable expression is expanded to the value (“false” or “true”) that is associated to an alternative identified by the “altName” name attribute.
  
  Therefore, the boolean value of an alternative can be used in conditional expressions to determine the selection of units, see Section 9, or to determine the setting of a derived variable, see Section 8.1.2.
• priority [type=nonNegativeInteger]
  This OPTIONAL attribute associates a non negative integer priority value to the alternative. A requirement MAY define multiple, non-exclusive alternatives. Multiple alternatives MAY be satisfied when the unit is able to deploy and configure itself in different ways, depending on the environment conditions. In order to determine the “use” relationships that the IU instance establishes with its pre-requisites it is important to know which one of the possible configuration alternatives is implemented during install.
  
  The priority attribute SHOULD be specified when there are non-exclusive alternatives in a requirement, more than one of which can be simultaneously satisfied, unless these should be treated as having the same priority (see below).
  
  Specifying the same or no priority value for multiple alternatives within the same requirement is interpreted as a declaration that any one of the satisfied alternatives in this priority group could be equivalently exploited. An implementation MAY request further external input to select one or more of these alternatives, e.g. during an interactive install.
  
  

Each alternative is defined as a sequence of elementary checks whose result should be verified. An elementary check is either referred to by the checkItem element – a reference to a predefined elementary check – or it can be defined inline by the inlineCheck element.

A checkItem element within an alternative has the following attributes:

• checkIdRef [type=IDREF]
  This REQUIRED attribute is a reference to the corresponding check and, implicitly, to the variable containing the boolean result of that elementary check.
• testValue [type=boolean]
  This OPTIONAL attribute defines the value of the check result for which the alternative is satisfied. When the attribute is not specified, the default value “true” is assumed. Specifying a value of “false” means that the check result MUST be the boolean “false” for the alternative to be satisfied. In the case of a software check, this means that the specified software IU is an “ex-requisite”.

An inlineCheck element MAY be used instead of a checkItem element to specify a check directly within an alternative element, that is, without making a reference to the result of an elementary check that is performed before the user input phase. An inline check is an instance of the group siu:CheckChoice, already illustrated in Section 7.

7.2.1           Uses relationships

Uses relationships are established during install between an installable unit and other software instances that constitute a dependency for the IU being created. The specific relationships being established are determined by the software dependencies declared in the IU and, in case of requirements with multiple alternatives, by the specific alternatives that were satisfied. The alternatives that are satisfied at install time SHOULD continue to be met during the unit’s life-cycle.

7.2.2           Example – Install requirements

The following example assumes that an SIU, implementing a JAVA application can be installed on an operating system hosting environment with the following requirements:

·        The SIU requires 0.2 Megabytes (200K) of free disk space.

·        The SIU requires 30 Megabytes of temporary disk space during install.

·        The OS must be Windows 2000, Windows XP or Red-Hat Linux.

·        The required maintenance levels of Windows 2000 are SP3 or SP4.

·        Only the versions of Red-Hat between 7.2 and 8.1 are supported

·        The DB2 product is required.

·        The SIU supported DB2 version on Linux is 7.1

·        On Windows the SIU supports any version of DB2 between 7.2 and 8.1.

·        The ACME Personal Firewall product (any version) must not be installed on Windows.

·        The SIU requires an IBM JRE.

·        The SIU supported JRE version on Linux is 1.3.1.

·        On Windows the SIU supports any JRE version between 1.3.1 and 1.4.1.

·        On Windows the SIU requires the IBM GS Kit v 4.0.2.49.

Here, for the sake of explaining custom checks, it is assumed that the last requirement cannot be checked by means of a standard software check. This situation might occur when the pre-requisite software is deployed by a native installer and signature information is not available to perform its discovery. 

Let us assume that the following elementary checks, each one referred to by the value of the checkId attribute, are defined within the checks section of the IU definition.

·        Permanent_Disk_Space_Check

·        Temporary_Disk_Space_Check

·        Windows_2000_Check

·        Windows_XP_Check

·        Linux_Check

·        Windows_version_Check

·        Linux_version_Check

·        db2_for_Windows_Check

·        db2_for_Linux_Check

·        JRE_for_Windows_Check

·        JRE_for_Linux_Check

·        ACME_Personal_Firewall_Check

·        GSK4_WinRegistry_Check

Each one of these checks is explained in detail in the following sections.  With the above assumptions, the SIU requirements can be expressed by the following XML fragment.

 

<requirement name="Install_Common_Reqmt" operations="Create">

<alternative name="isDiskSpaceAvailable">

        <checkItem checkIdRef="Permanent_Disk_Space_Check" />

        <checkItem checkIdRef="Temporary_Disk_Space_Check" />

</alternative>

</requirement>

<requirement name="Install_Dependencies_Reqmt" operations="Create">

<alternative name="isLinux_Alternative_Satisfied">

        <checkItem checkIdRef="Linux_Check" />

        <checkItem checkIdRef="Linux_version_Check" />

        <checkItem checkIdRef="db2_for_Linux_Check" />

        <checkItem checkIdRef="JRE_for_Linux_Check" />

</alternative>

<alternative name="isWin2K_Alternative_Satisfied">

        <checkItem checkIdRef="Windows_2000_Check" />

        <checkItem checkIdRef="Windows_version_Check" />

        <checkItem checkIdRef="db2_for_Windows_Check" />

        <checkItem checkIdRef="JRE_for_Windows_Check" />

        <checkItem checkIdRef="ACME_Personal_Firewall_Check" testValue="false" />

</alternative>

<alternative name="isWinXP_Alternative_Satisfied">

        <checkItem checkIdRef="Windows_XP_Check" />

        <checkItem checkIdRef="db2_for_Windows_Check" />

        <checkItem checkIdRef="JRE_for_Windows_Check" />

        <checkItem checkIdRef="ACME_Personal_Firewall_Check" testValue="false" />

</alternative>

</requirement>

There are two requirements in the above example that are both declared to apply to the “Create” operation. The first one factors the common requirements (permanent and temporary space) that must be satisfied on any operating system platform. There is a single alternative in this requirement, and it does not have an associated name. The second requirement can be satisfied by any one of the listed alternatives (three). Of the following checks

·        Linux_Check,

·        Windows_2000_Check and

·        Windows_XP_Check

only one is expected to be possibly “true” on a given operating system hosting environment. This fact makes the three alternatives mutually exclusive and it therefore eliminates the need of assigning each alternative a priority.

7.2.3           Example – Adding Requirements for Configuration

Some installable units may not need to declare requirements for any operation other than Create. This is the case if it can be assumed that the execution of other operations like Configure or Delete should not require additional resources. In general however, there may be extra consumption resources (such as temporary disk space) that are needed during any of the successive operations (Configure, Verify) that may be performed during the IU life-cycle.

 

Requirements can be added that list the checks that must be executed when executing one or more operations. In the current example, let assume that there are actions, within this unit of software, executing a configuration program during the Configure operation. Also assume that this configuration program need some temporary disk space to run. A second requirement can be added to the sequence causing the following checks to be executed during Configure:

 

·        Ensure there is enough temporary space for the configuration program to execute. This requires to define a new check (ConfigData_Temp_Space_Check)

The following XML fragment illustrates the added requirement.

 

<requirement name="Configure_Reqmt" operations="Configure">

<alternative name="isDiskSpaceForConfigureAvailable">

        <checkItem checkIdRef="ConfigData_Temp_Space_Check" />

</alternative>

</requirement>

 

7.2.4           Example – Declaring non exclusive alternatives

In this example, an SIU MAY initially configure itself to work with one or more database systems: DB_X, DB_Y or DB_Z This situation might be expressed as a requirement with three alternatives, respectively associated to the following variables:

·        isDBX_Installed,

·        isDBY_Installed, and

·        isDBZ_Installed.

DB_X and DB_Y are the preferred choice: there may be Create and InitialConfig artifacts in the SIU that install and initially configure the IU to work with DB_X, DB_Y or both DB_X and DB_Y. The SIU should only install and initially configure the code for working with DB_Z if neither of the other databases are installed.

Multiple artifact sets can be associated to the SIU, see Section 9.3, each one through a different unit element. Each unit element is conditioned, so it is possible to use the results of checks to determine which unit should be processed depending on the environment. Assume now that there are three independent artifact sets associated to the SIU, each one capable of deploying and configuring code to work with one specific database. The units (artifact sets) associated to the above databases are controlled by the following conditions:

·        DB_X unit condition:
“isDBX_Installed”;

·        DB_Y unit condition:
“isDBY_Installed”;

·        DB_Z unit condition:
 “isDBZ_Installed AND NOT (isDBX_Installed OR isDBY_Installed)”.

Declaring a priority for each of the above alternatives is a means to make the installer aware of the unit’s install and configuration intents without any need for the installer to infer the same information from an analysis of the conditions which depend on each alternative variable.

This is obtained by assigning the isDBZ_Installed alternative priority = 1 (the lowest) and by assigning the same and higher priority value – 2 – to the other two alternatives.   

 

       <requirement name="ConfigureDatabases" operations="Install">

                     <alternative name="isDBX_Installed" priority="2">

                        <checkItem checkVarName="DBX_Check" />

                     </alternative>

                     <alternative name="isDBY_Installed" priority="2">

                        <checkItem checkVarName="DBY_Check" />

                     </alternative>

                     <alternative name="isDBZ_Installed" priority="1">

                        <checkItem checkVarName="DBZ_Check" />

                     </alternative>

        </requirement>

 

As explained in Section 7.2.1 above, the Uses relationships of the installable unit are determined by the alternatives that are satisfied at install time and that are part of the set with the highest assigned priority value. The selected alternatives SHOULD continue to be satisfied during the entire life-cycle of the installable unit.

7.2.5           Requirements in referenced installable units

A referenced installable unit definition, see Section 6.2, MAY include additional requirements that need to be satisfied by one or more topology targets defined in the aggregating root IU. In that case, both the requirements specified within the referenced IU descriptor and in the aggregating root IU MUST be processed: these additional specifications do NOT override any requirements stated in the referenced IU descriptor. An implementation MAY choose to optimize the checks it performs, e.g. it MAY only perform the most stringent version range check or capacity check; it SHOULD check the total consumption requirement.

7.3 Built-in checks

Checks described in this Section can be performed without providing user code.

7.3.1           Capacity check

 

A capacity check is used to check the value of a named property defining some capacity of the target hosting environment. Each hosting environment type should define the set of capacity properties that it supports and the units in which these are expressed.

A capacity check element has the following attributes and elements, in addition to the ones inherited by base:Check.

·        type [anonymous type]
This OPTIONAL attribute may assume one of the following enumerated values:

o       “minimum” (default)
The value of the named property MUST be equal or exceed the value specified in the check definition.

o       “maximum”
The value of the named property MUST NOT exceed the value specified in the check definition.

·        propertyName [type=base:PropertyName]
This REQUIRED element is used to specify the name of a hosting environment capacity property.

·        value [type=base:VariableExpression]
This REQUIRED element is used to specify the threshold value (maximum or minimum) of the property. If there are two capacity checks for the same property and type= “minimum” only the one with the highest value needs to be considered. If there are two capacity checks for the same property and type= “maximum” only the one with the lowest value needs to be considered.

7.3.1.1               Example

In the following example, “Processor/CurrentClockSpeed” is assumed[4] to be the name of a property exposing the processor frequency in MegaHertz in the operating system hosting environment, and the check is used to determine whether the processor speed is at least 400Mhz. 

 

<capacity checkId="ProcessorSpeed_Check" type="minimum">

    <propertyName>Processor/CurrentClockSpeed</propertyName>

    <value>400</value>

</capacity>

7.3.2           Consumption check

 

A consumption check is used to check the availability of resources to be consumed on the hosting environment. Typical examples of consumption properties on the operating system hosting environment are disk space and memory. The consumption requirement can be temporary or permanent. Multiple consumption requirements for the same property on the same container are automatically cumulated. Each hosting environment type should define the set of consumption properties that it supports and the units in which these are expressed.

 

A consumption check element has the following attributes and elements, in addition to the ones inherited by base:Check.

·        temporary [type=boolean]
When this OPTIONAL attribute has a value of “true” the requested quantity of the named property is only needed during installation. The default value is “false”.

·        propertyName [type=base:PropertyName]
This REQUIRED element is used to specify the name of a hosting environment consumption property.

·        value [type=base:VariableExpression]
This REQUIRED element is used to specify the consumed amount of the property. The value of the named consumption property MUST be equal or exceed the sum of the values specified for the same property over the installable units being deployed to the same hosting environment..

7.3.2.1               Example

“TotalVisibleMemorySize” and “FileSystem/AvailableSpace”  are assumed to be the names, in the following example, of properties exposed by the operating system hosting environment which respectively determine the core memory available for applications, in bytes, and available disk space for file allocations. The checks determine if 131072 bytes of memory can be allocated to the IU, when in the running state, and if 30.3 megabytes of temporary disk space are available during installation.

 

<consumption checkId="Memory_Check">

    <propertyName>TotalVisibleMemorySize</propertyName>

    <value>131072</value>

</consumption>

 

<consumption checkId="Temporary_Disk_Space_Check" temporary="true">

    <propertyName>FileSystem/AvailableSpace</propertyName>

    <value>30</value>

</consumption>

 

Note that there may be multiple filesystems in the operating system that can satisfy the consumption requirement. The above diskspace check will be satisfied if any of the filesystems can satisfy the requirement. Note, however, that it is the cumulative amount of diskspace that must be satisfied by a single filesystem. If checks may be satisfied by multiple filesystem instances, the requirement should be expressed using the targetRef attribute on each check. Each check would indicate the logical instance of a “Filesystem” resource hosted by the operating system that is to satisfy the check.

7.3.3           Property check

 

A property check is used to check the value of a property defined for a manageable resource. Each resource type should define the set of properties that it supports.

A property check has the following elements, in addition to the ones inherited by base:Check.

·        propertyName [type=base:PropertyName]
This REQUIRED element is used to specify the name of a property being checked on a target resource.

The property check definition MUST include one of the three following elements (members of a CHOICE)

·        pattern [type=string]
This element provides a string value to be interpreted as a regular expression. The string value MUST be a valid instance of an XML pattern facet. The regular expression SHOULD match the property (string) value.

·        value [type=base:VariableExpression]
The property value MUST be identical to the one provided by this element.

·        rootOfPath [type=base:VariableExpression]
This element provides a value to be interpreted as the full path name of a given resource (e.g. a file), in which case the property specified by the propertyName element should provide the path name of a unique context for that type of resource (e.g. a filesystem where files are stored). There is a single target instance satisfying the check (see an example in the following section). The name of properties that support  this variant of the check must be obtained from the documentation of each target resource. 

 

7.3.3.1               Examples

In the following example, “OsType” is assumed to be the name of a property exposing the operating system type according to the definition of the “OperatingSystem” type in CIM 2.8, see [CIM2.8].

 

<property checkId="Windows_2000_Check">

    <propertyName>OsType</propertyName>

    <value>Windows 2000</value>

</property>

 

<property checkId="Windows_XP_Check">

    <propertyName>OsType</propertyName>

    <value>Windows XP</value>

</property>

 

<property checkId="Linux_Check">

    <propertyName>OsType</propertyName>

    <value>LINUX</value>

</property>

 

 

In the following example, “root” is assumed to be the property exposed by a file system type of resource, representing the root of path names for all files and directories stored in a file system instance. The following property check is satisfied by the unique instance hosting the directory whose path name is declared by the rootOfPath element.

 

 

<property checkId="FileSystem_Check" targetRef="FileSystem_Target">

    <propertyName>root</propertyName>

    <rootOfPath>$(InstallDirectory)</rootOfPath>

</property>

 

 

7.3.4           Version check

 

A version check is used to check the value of a property of a target resource that has the characteristics of a version. The actual names of properties holding version information should be obtained from the documentation of each specific resource.

Any version property associated to a generic resource or hosting environment MUST have values in the range defined for the vsn:GenericVersionString type. The format and comparison rules for version strings are defined in Section 19. 

A version check element has the following elements in addition to the ones inherited by base:Check.

·        propertyName [type=base:PropertyName]
This REQUIRED element is used to specify the name of a property whose values MUST be in the format defined by the vsn:GenericVersionString type.

At least one of the following two elements MUST be specified. 

·        minVersion [type=vsn:GenericVersionString]
This is the minimum value that can pass the version check. 

·        maxVersion [type=vsn:GenericVersionString]
This is the maximum value that can pass the version check. 

7.3.4.1               Example

In the following example, “version” is assumed to be the name of a property exposing the Windows operating system version and service pack level in a format compatible with vsn:GenericVersionString.

 

        <version checkVarName="Windows_version_Check">

           <propertyName>version</propertyName>

           <minVersion>5.0.2195.3</minVersion>

           <maxVersion>5.0.2195.4</maxVersion>

        </version>

 

It should be noted that for a property to qualify for version identification it MUST be possible to determine which one of two possible values is an antecedent of the other. This MAY be obtained by combining into the version property information that may be associated to different “native” properties. In the above example, information relative to the Windows 2000 release (5.0) and version (2195+ServicePack_4) is arranged in four version parts. A definition of the actual structure of the version property being checked should be obtained from the documentation of each specific resource.

7.3.5           Software check

A software check is used to determine whether a software resource is hosted in the target hosting environment. Software resources include software that has been installed by means other than the descriptor defined in this specification. This contrasts with the installable unit check described in the following section, which is intended to determine the presence of a deployed installable unit in the hosting environment.

 

A software check has the following attributes, in addition to the ones inherited by base:Check.

·        type [type=base:RequisiteType]
This OPTIONAL attribute can assume one of the following two values:

o       “pre_requisite” (default)
A “pre_requisite” must be installed before the dependent IU is installed.

o       “requisite”
A “requisite” must be installed before the dependent IU is Usable.

·        exactRange [type=boolean]
This OPTIONAL attribute determines whether the check may be satisfied by a backwards-compatible version of the software resource. This attribute SHOULD NOT be specified – it SHOULD be ignored if it is specified – when the UUID element is NOT specified (see below). The value defaults to “false”, which means that the check CAN be satisfied by a backwards-compatible version: i.e. the check will be passed when a newer version than maxVersion is found which declares itself to be backward compatible with a version level comprised between minVersion and maxVersion.

A software check has the following elements, in addition to the check description element inherited from base:Check. All the elements are OPTIONAL. However at least one of UUID and name MUST be specified.

·        UUID [type=base:UUID]
The UUID of an installable unit, if one exists, that defines the required unit of software.

·        name [type=base:PatternOrValue]
The type of this element has an OPTIONAL boolean attribute – pattern.

o       pattern [type=boolean]

When the element  does NOT specify this attribute, OR the element does specify the pattern attribute with a value of “false” – “false” is the default – the content string is used to perform an equality comparison test with the name of a software resource hosted by the target.

When the element  is specified with the pattern attribute value of “true” the string content MUST be a valid instance of an XML pattern facet and it is interpreted as a regular expression to match the name associated to an installed unit of software hosted by the target.

·        minVersion [type=vsn:GenericVersionString]
This is the minimum value that can pass the version check. 

·        maxVersion [type=vsn:GenericVersionString]
This is the maximum value that can pass the version check. 

·        canBeSatisfiedBy [type=IDREF]
Reference to the IUName of a bundled requisite in the root IU, see Section 5.7. The bundled requisite SHOULD be installed on the target instance if needed to satisfy a requirement associated to this check.

A software check MAY specify only the name of the software unit to be checked, OR it MAY specify both the UUID and name.

A software check MAY specify only the UUID of the software unit to be checked, in which case the name of the software resource to be checked SHOULD be retrieved from an IUDD descriptor associated to that resource. See also the following Section 7.3.6 for a definition of installable unit checks.

A software check SHOULD be used when the required software resource MAY NOT have an IUDD or it MAY have been deployed by means of a legacy installer, not enabled to process and register IUDD information. Both UUID and name SHOULD be provided when the IUDD for the software dependency is available, in order to enable the use of a backward compatible hosted resource that MAY have a different name (see below).

Different hosting environments may support different types of software resources (e.g. installed programs in the operating system; J2EE applications in the J2EE environment), or may not host any form of software resource[5].

The software resource may be recorded in a legacy registry that also includes version information. For that reason, the version elements in a software check are instances of the type vsn:GenericVersionString, and NOT of the vsn:VersionString type, which defines a strict V.R.M.L format (see Section 19).

A software check establishes a dependency to a hosted software resource and not to an IU instance.

The UUID information, when specified, SHOULD be used to locate a matching IU descriptor. If an IU descriptor matching the UUID is found whose version and backward compatibility declarations make a corresponding IU instance a candidate to satisfy the software dependency, the name specified in that descriptor is used to perform the search over the hosting environment hosted resources. An exact version matching is required (a backward compatibility declaration is ignored, if present) when the exact_range attribute is specified by the software check. Note that the search on hosted resources would fail if the IU was installed and registered with its UUID but it is not known to the hosting environment by the name specified in the descriptor. The diagram of Figure 10 illustrates the UUID processing.  In this example, it causes the selection of a hosted resource with a later version and a different name.  

 

Figure 10: Use of UUID in a software check

7.3.5.1               Example

        <software checkVarName="db2_for_Linux_check">

           <UUID>12345678901234567890123456789012</UUID>

           <name pattern="true">(DB2|Universal Database)</name>

           <minVersion>7.1</minVersion>

        </software>

        <software checkVarName="db2_for_Windows_check">

           <UUID>22345678901234567890123456789012</UUID>

           <name pattern="true">(DB2|Universal Database)</name>

           <minVersion>7.2</minVersion>

           <maxVersion>8.1</maxVersion>

        </software>

        <software checkVarName="JRE_for_Linux_check">

           <UUID>13345678901234567890123456789012</UUID>

           <name pattern="true">(IBM+.*J2RE)</name>

           <minVersion>1.3.1</minVersion>

           <maxVersion>1.3.1</maxVersion>

        </software>

        <software checkVarName="JRE_for_Windows_check">

           <UUID>12445678901234567890123456789012</UUID>

           <name pattern="true">(IBM+.*J2RE)</name>

           <minVersion>1.3.1</minVersion>

           <maxVersion>1.4.1</maxVersion>

        </software>

        <software checkVarName="ACME_Personal_Firewall_Check">

           <name pattern="true">(ACME+.*Personal Firewall)</name>

        </software>

 

7.3.6           Installable Unit Check

The installable unit check differs from the software check (see above section 7.3.5) in that it is intended to perform checks on installable units based on identity and other information declared in their IU descriptor. This information SHOULD be persisted for an IU instance that is created or modified. Ideally, this information would be periodically verified against the actual resources held in hosting environments.

The IU check tests that an instance of a named IU, feature or fix exists within a given hosting environment. If the IU spans hosting environments, this check tests for the existence of any subcomponent within the target hosting environment.

An IU check supports different ways to identify the IU whose availability needs to be checked. In particular, when the IUNameRef OR the featureIdRef element is specified, the IU check is intended to represent an internal dependency check. This type of check does NOT require to be verified against a hosting environment during Create. Note that an internal dependency does NOT cause an implicit selection of a feature or an inline IU: the semantic is that the dependent IU must be selected – if conditioned, the condition MUST be satisfied – for the IU check to be positively verified. 

An installable unit check has the same attributes as a software check, defined in the previous Section 7.3.5.

·        type [type=base:RequisiteType]
This OPTIONAL attribute can assume one of the following two values:

o       “pre_requisite” (default)

o       “requisite”

·        exactRange [type=boolean]
This OPTIONAL attribute determines whether the check may be satisfied by a backwards-compatible version of the IU.

An installable unit check inherits a description element from the base type base:Check. The IU check consists of either a standard IU check, an internal IU dependency check, or an internal feature dependency check. These three variants of the check correspond each to an element of an XML schema choice construct, and are separately described below, each in a separate sub-section.

7.3.6.1               Standard IU Check

A standard IU check has the following elements, in addition to the check description element inherited from base:Check. All the elements are OPTIONAL. However at least one of UUID and name MUST be specified.

·        UUID [type=base:UUID]
This is the UUID of the installable unit, as defined in the IU identity.

·        name [type=token]
This is the name of the installable unit, as defined in the IU identity.

·        minVersion [type=vsn:VersionString]
This is the minimum V.R.M.L. value that can pass the version check. 

·        maxVersion [type=vsn:VersionString]
This is the maximum V.R.M.L. value that can pass the version check. 

·        temporaryFixes [type=base:ListOfIdentifiers]
This is a list of NCName type of items. Each item identifies a required temporary fix by a value that MUST correspond to the fix name as specified by the fixName element in the fix definition.
This element MUST list all the names of fixes that are REQUIRED to be applied to the IU.   

·        features [anonymous type]
If specified, this element contains a sequence of one or more name elements, each one identifying a required IU feature:

o       name [type=token]
The value of this element MUST correspond to the name element in the feature identity definition. 

·        canBeSatisfiedBy [type=IDREF]
Reference to the IUName of a bundled requisite in the root IU, see Section 5.7. The bundled requisite SHOULD be installed on the target instance if needed to satisfy a requirement associated to this check.

7.3.6.2               Internal IU Check

An internal IU check specifies the internal identifier of an IU, within the root IU. The check is verified – i.e. the check result is “true” – if the identified IU is also installed. The identified IU MAY be defined among the selectable contents, in which case the result of the check depends on feature selections, see Section 5.4. The identified IU MAY have an associated condition, in which case the result of the check depends on variables – including parameters, derived variables, check results and requirement alternative results – that MAY be referenced by the condition.

·        IUNameRef [type=IDREF]
This is a reference to the IU  that MUST be installed for the check to be verified. The value MUST match the IUName attribute of an IU within the descriptor.

7.3.6.3               Internal Feature Check

An internal feature check specifies the internal identifier of a feature within the root IU. The check is verified – i.e. the check result is “true” – if the identified IU is already installed or is selected to be installed. The identified IU MAY be defined among the selectable contents, in which case the result of the check depends on feature selections, see Section 5.4. The identified IU MAY have an associated condition, in which case the result of the check depends on variables – including parameters, derived variables, check results and requirement alternative results – that MAY be referenced by the condition.

·        featureIDRef [type=IDREF]
This is a reference to a feature  that MUST be installed for the check to be verified. The value MUST match the featureID attribute of a feature defined within the descriptor.

7.3.7           Relationship Check

Relationship checks describe a specific relationship that MUST exist between a target and another manageable resource. The structure of the relationship check is illustrated in the diagram below:

The relationship check inherits the checkId and targetRef attributes from the base type base:Check. In particular, the targetRef attribute identifies the topology target that MUST satisfy the relationship check. The check is specified in two parts.

1.      The identifier of the related target participating in the relationship.
Exactly one of the following three elements MUST be specified depending on whether the relationship has an implied direction (such as Hosts) or is a peer relationship. The referenced target MUST be defined within the root IU descriptor.

·        source [type=IDREF]
This element indicates that the target identified by the targetRef attribute of the relationship check is the source of a directional relationship with a related target identified by this element. 

·        sink [type=IDREF]
This element indicates that the target identified by the targetRef attribute of the relationship check is the sink of a directional relationship with a related target identified by this element.

·        peer [type=IDREF]
This element indicates that the target identified by the targetRef attribute of the relationship check and the one identified by this element are in a peer relationship.

2.      The name of the required relationship type, specified by the following element.

·        type [type=rel:Relationship]
This element is an instance of rel:Relationship, a type which defines the range of admissible relationship types. This type is a union of rel:StandardRelationship – defining a set of standard association stereotypes – and the Name XML type. An association stereotype defines a category of associations (relationships) with a common semantics.

For example, if target A is to be the host of another target B, then the relationship is specified as:

<target id="A" …>
    …
   <relationship checkId=”AHostsB”>
      <sink>B</sink>
      <type>Hosts</type>
   </relationship>

    …
</target>

Conversely, if target A is to be hosted by target B, then the relationship is specified as:

<target id="A" …>
    …
   <relationship checkId=”BHostsA”>
      <source>B</source>
      <type>Hosts</type>
   </relationship>

    …
</target>

7.3.8           Custom Check

A custom check defines the execution of a check artifact on a target.

Like any artifact (see Section 9.5) check artifacts may have their variables initialized via a parameter map. The same check artifact could be referenced by multiple custom checks testing different sets of conditions, each set of conditions being associated to the values of variables passed into the artifact. The actual definition of the custom check artifact to be executed is not included within each individual check. Artifacts referenced by custom checks are defined within the root IU element customCheckDefinitions introduced in Section 5.3, and illustrated in the following diagram.

Custom check definitions in the rootIU element are OPTIONAL.

A customCheckArtifact element – instance of siu:CustomCheckArtifact, derived from the siu:Artifact type described in Section  9.5 – includes the same elements that are common to all artifact definitions, namely:

·        fileIdRef [type=IDREF]
This REQUIRED attribute is a reference to a file element in the root IU defining the bundled artifact descriptor file. It MUST be a valid reference to a file element within the root IU files element.

·        type [type=siu:ArtifactFormat]
This OPTIONAL attribute is used to declare whether the artifact defines actions or resource property definitions. The supplied default value (“ActionDefinition”) is appropriate for a custom check artifact and it SHOULD NOT be overridden with a different value. This restriction SHOULD be enforced by the implementation; although it is not enforced by the schema.

·        parameterMaps [type=base:Maps]
This OPTIONAL attribute is used to declare mappings between variables in the IUDD and variables defined in the artifact. This is a sequence of map elements, each one associating an IUDD variable (internalName)  to an artifact variable (externalName).  Parameter maps are explained in Section 9.5 for SIU and CU artifacts. Each map element has a direction attribute. SIU and CU artifacts only support the default value (“in”) meaning that the IUDD variable is used to initialize the artifact variable. However, a map associated to a check  artifact can specify the direction attribute to be “out” thus requiring that the value of the artifact variable MUST be obtained at the end of the check artifact execution and used to set the corresponding IUDD variable.  

 

It is REQUIRED that a check artifact define a “checkResult” variable whose value at the end of the check artifact execution MUST indicate the boolean result (“true” or “false”) of the custom check. A parameter map for the “checkResult” artifact variable SHOULD NOT be defined (the result boolean value is used to set the  variable implicitly associated to the check, see Section 7.1.1). As a “side-effect” of executing a custom check with parameter maps specifying the “out” value of the direction attribute, one or more IUDD variables may have their values changed.

While most of the semantic associated to a custom check depends on the above custom check artifact definition, the behavior of the check also depends on the values of IUDD variables that are passed (direction “in”) into the artifact variables. As explained below, the custom check (invocation) allows to specify new values for these IUDD variables, whose change MUST be effective prior to the mapping.  

A custom check has the following attribute in addition to the ones inherited from base:Check.

·        artifactIdRef [type=IDREF]
This REQUIRED attribute is a reference to a custom check command definition. It MUST be a valid reference to a CustomCheckArtifact element within the root IU element customCheckdefinitions.

A custom check may include one or more instances of the following element

·        parameter [anonymous type]
The type of this element is derived from base:VariableExpression. This element is used to to specify a value for a variable which must be set  with the specified value before any parameter map with direction “in” is processed in the corresponding check artifact definition. The element includes the following attribute

o       variableNameRef [type=IDREF] 
This attribute is used to identify the variable for which a value if provided. 

Some IUDD variables appearing with direction “in” in the artifact definition may not need to be set for each specific check, i.e they retain the same value across different checks, in which case these variables  do not need to be set by a parameter element in the custom check.

Note that implementing software pre-requisite checking through custom checks (external commands) makes it impossible for an implementation to record a relationship between the unit being installed and the pre-requisite software resources.

The following is an example custom check declaration:

 

<custom artifactIdRef="winRegCustomCheck" checkId="GSK4_Win_Registry_Check">

<parameter variableNameRef="Win_Reg_Hive">HKEY_LOCAL_MACHINE</parameter>

<parameter

variableNameRef="Win_Reg_Key">SOFTWARE\IBM\GSK4\CurrentVersion\Version</parameter>

<parameter variableNameRef="Win_Reg_Type">REG_SZ</parameter>

<parameter variableNameRef="Win_Reg_Value">4.0.2.49</parameter>

</custom>

 

The above example assumes that “winRegCustomCheck” is the identifier of a check artifact defined in the IU descriptor, checking the value of a specified  registry key for equality against a specified value. The check artifact definition corresponding is given below:

 

<customCheckArtifact artifactId="winRegCustomCheck">

<fileIdRef>WinRegistryCheckArtifact</fileIdRef>

<parameterMaps>

 <map>

        <internalName>Win_Reg_Hive</internalName>

        <externalName>Reg_Hive</externalName>

 </map>

 <map>

        <internalName>Win_Reg_Key</internalName>

        <externalName>Reg_Key</externalName>

 </map>

 <map>

        <internalName>Win_Reg_Type</internalName>

        <externalName>Reg_Type</externalName>

 </map>

 <map>

        <internalName>Win_Reg_Value</internalName>

        <externalName>Reg_Value</externalName>

 </map>

</parameterMaps>

</customCheckArtifact>

In this example, the parameter elements in the custom check (invocation) assign values to the four parameter variables that are mapped to artifact variables within the custom check artifact definition.

 

8         Variables, Expressions and Conditions

Variables support late binding of additional information to an IU descriptor. This information may be obtained from user input, from a target property query or from other sources. Variables can be referenced within a schema when defining the value of an attribute or element that is an instance of base:VariableExpression. Symbolic references to a variable are substituted by the variable value when the expression is evaluated. Expressions producing a boolean result value are used in conditions. Conditions MAY be associated to an installable unit definition. They MAY be also associated to expressions within a derived variable definition.

8.1 Variables

A variable can be one of several types, as described below:

·        It is a parameter, provided by user input, response file or from an encapsulating installable unit (see Section 8.1.1).

·        It is derived from a variable expression (see Section 8.1.2).

·        It is defined as a query against a target (see Section 8.1.3).

·        It is defined as a query against an IU instance, returning the IU instance discriminant. This is the value that uniquely identifies an IU instance within a hosting environment, for example, the install location for an IU installed into the operating system (see Section 8.1.4).

·        It is specified as a resolved target list (see Section 8.1.5).

·        It is specified by an IU update as a variable inheriting its value from a variable that was defined in a previous level of the same IU instance (see Section 8.1.6).

In addition to the above variables, which are explicitly declared, a variable expression MAY contain a reference to the boolean result of a check, see Section 7.1.1, or to the boolean result of a requirement alternative, see Section 7.2.  

One or more variables MAY be defined by the element variables within an IU. This is a sequence of one or more variable elements, instances of base:Variable. Each one identifies a named variable that is needed to deploy the installable unit. The variable MAY have a locale-sensitive description.

The above six forms of a variable definition are all represented in the following diagram for the schema type base:Variable

 

A variable MUST specify the following attribute

·        name [type=ID]
This REQUIRED attribute is an identifier that can be used to refer to the variable. The value MUST be unique within the descriptor.

A variable MAY specify the following element

·        description [type=base:DisplayElement]
This OPTIONAL element allows to associate text labels and a description with this variable. See Section 17 for a general description of display elements and their localization.

A variable MUST specify one of the six elements defined by the XML schema choice construct. These are defined in the sections below.

8.1.1           Parameter

The parameter element defines a parameter variable. The value MAY be provided by user input, response file or from an encapsulating installable unit descriptor via a parameter map.

·        parameter [anonymous type]
 The following attributes MAY be specified for this element

o       defaultValue [type=base:VariableExpression]
This OPTIONAL attribute provides a default initial value for the parameter variable. If no default value is specified, and no value is provided by user input, response file or parameter map from an aggregating IU, the value of the parameter variable is undefined. An error SHOULD be generated when trying to access a parameter with an undefined value.

o       transient [type=boolean]
This OPTIONAL attribute is used to indicate that this variable contains information (e.g. a password) that SHOULD NOT be permanently stored, either because it is transient – the current value may become invalid – or because the current value represents sensitive user information. If needed on successive life-cycle operations associated to a deployed IU instance, the current value will have to be supplied.

8.1.1.1               Example

<variable name="installToAllUsers">

   <parameter defaultValue="true"/>

</variable>

 

In the absence of an overriding value, the above definition of a variable named “installToAllUsers” causes the default value (“true”) to be retained.

8.1.2           Derived Variable

The derivedVariable element defines a derived variable.

·        derivedVariable [anonymous type]
The element MUST include one or more instances of the following elements, each one  defining a candidate value for this variable:

o       expression [anonymous type]
The type of this element is derived from base:VariableExpression, and it includes the following OPTIONAL attributes:

§         condition [type=base:VariableExpression]
This attribute is used to specify a condition for this expression. If more than one variable expression is provided, each one SHOULD be qualified using a condition. The value of this expression should be assigned to the derived variable if this condition is “true”. The variable expression for this attribute may include references to the boolean result value of a check  or to the boolean result of a requirement alternative.  A derived variable depending on the outcome of checks and alternatives may be made available within artifacts, through parameter maps, to determine the appropriate behavior of actions.

§         priority [type=nonNegativeInteger]
The attribute specifies a priority for this expression. A priority MUST be specified when multiple expressions are defined. If multiple expressions have their conditions satisfied, the variable will be set to contain the value of the expression with the highest priority value (where “5” is a higher priority than “1”). Two expressions SHOULD NOT specify the same priority. 

8.1.2.1               Example

<variable name="install_root">

 <derivedVariable>

    <expression condition="$(Windows_Check)">C:\Program Files</expression>

    <expression condition="$(Linux_Check)">/usr/opt</expression>

  </derivedVariable>

</variable>

In the above example, the variable named “install_root” is set to the value “C:\ProgramFiles” or to the value “/us/opt” depending on alternative conditions. In this example, it is assumed that the variable expression associated to each condition is the boolean result (“true” or “false”) of an elementary check.  It is also assumed that the two checks cannot be simultaneously satisfied on the same hosting environment, therefore there is no need to specify a priority.

8.1.3           Property Query

The queryProperty element defines a variable whose value is the result of a query. Queries MAY be specified against a target that resolves to multiple physical instances, based on the scope value (“all” or “some”).

When the variable is defined within a single-target IU and the target T is identical to the IU hosting environment, the IU instance being deployed to a physical instance T_i of the IU target T SHOULD “see” the variable to contain the property value obtained from the same instance.

A query property variable defined within a multi-target IU SHOULD result in a comma-separated list of values when the target resolves to multiple physical instances. All lists associated to different query property variables defined for the same target SHOULD have the value associated to a given target instance in the same position. The ordering of values in the list SHOULD be consistent with the sequence of target identifiers associated to a resolvedTargetList variable defined for the same target, see Section 8.1.5.

·        queryProperty [anonymous type]
This element defines the name of a property to be queried, and optionally the target on which the query SHOULD be performed.

o       propertyName [type=base:PropertyName]
This REQUIRED attribute defines the name of the property to be queried.

o       targetRef [type=IDREF]
This OPTIONAL attribute may be used to specify the target on which the query SHOULD be performed. A variable definition within a single target IU is NOT REQUIRED to specify the target: if a target is not specified, the query is performed on the IU target hosting environment. This attribute SHOULD be specified if the variable definition is NOT within a single target IU. If the attribute is specified, the value MUST be a valid reference to a target of a deployed target within the root IU.

If targetRef is specified for a single target IU and it is different from the IU target, then EITHER the target has a scope of “one” OR it SHOULD be possible to navigate relationships connecting the IU target to the query target so that one and only one instance of the query target is reached from the IU target. In the first case, the single target instance SHOULD be queried. In the second case, the instance of the single target IU being deployed to an instance “X” of the IU target will “see” the variable to contain the property value from the instance  “Y” of the query target that is reached by navigation of the existing relationships.

 

8.1.3.1               Example

<variable name="database_name">

 <queryProperty property="name" targetRef="tDatabase" />

</variable>

In the above example, a query variable is defined to obtain the name of a database. The example assumes that the topology target “tDatabase” defines a manageable resource that exposes the needed database name via the “name” property. 

8.1.4           IU Discriminant Query

The queryIUDiscriminant element defines a variable whose value is the IU discriminant of an installed IU instance. The IU instance discriminant is the value that uniquely identifies an IU instance within a hosting environment, for example, the install location for an IU installed into the operating system.

·        queryIUDiscriminant [anonymous type]
This element defines the IU instance to be queried by reference to an IU check, see Section 7.3.6, within the scope of the IU.
 
Use of a discriminant variable requires that the specific instance of an IU satisfying the IU check MUST be identified. When multiple IU instances satisfy the check, the user or the install runtime MUST select one instance. The returned discriminant value MUST be the one associated with the instance that is used within the root IU to satisfy the check.

The check referenced by a variable defined at the root IU level MUST be defined within a root IU topology target, as these are the only checks in scope for a variable in the root IU. However, the variable MUST not be referenced outside the scope of an IU that is aimed on that target.

o       iuCheckRef [type=IDREF]
This REQUIRED attribute MUST correspond to the checkId of an IU check defined in the descriptor: it SHOULD correspond to the checkId of a check that is in scope, see Section 7.1.1.  

 

8.1.4.1               Example

<variable name="Linux_JRE_Home">

   <queryIUDiscriminant iuCheckRef="JRE_for_Linux_check" />

</variable>

In the above example, the variable named “Linux_JRE_Home” is set to the value of the install location of the installable unit instance satisfying the IU  check named “JRE_for_Linux_Check”.

8.1.5           Resolved Target List

A resolvedTargetList is a variable whose value consists of the manageable resource IDs (handles) of the actual resource or resources corresponding to a specified target. It is assumed that a manageable resource id can be represented by a string that does NOT contain a comma character. Where a target resolves to more than one actual resource, the result is a comma-separated list. In that case, the ordering of identifiers in the list SHOULD be the same applied to the sequence of values of any property query on the same target that produces a list result, see Section 8.1.3.

A typical usage scenario for this capability is when a deployment application delegates some aspects of deployment or configuration. In this case, the hosting environment to which deployment is delegated needs to be aware of the target topology for the components within its domain. Example: an SIU represents a J2EE application that is targeted at T_DM – a topology target representing the domain manager of a J2EE administrative domain. However, one of the deployment parameters that needs to be specified for the SIU artifact is the list of servers within the domain onto which the application needs to be deployed. Another topology target T_AS is defined in this example to represent the specific set of J2EE application servers in the J2EE domain. A “Hosts” relationship is required between  T_DM and T_AS, and additional requirements may be defined for T_AS. A resolvedTargetList variable defined for T_AS  provides the needed list of servers that the SIU can pass into the artifact using a parameter map, so that it can be processed by the hosting environment T_DM.

·        resolvedTargetList [anonymous type]
The resolvedTargetList element defines a variable whose value is set to contain a list of manageable resource IDs, one for each selected instance of a topology target identified by the targetRef attribute.

o       targetRef [type=IDREF]
This REQUIRED attribute is used to specify the target whose resolved instances are identified by this variable. The value MUST be a valid reference to a topology target or deployed target in the root IU.  

8.1.5.1               Example

<variable name="Actual_Targets">

       <resolvedTargetList targetRef="Solution_Server" />

</variable>

 

8.1.6           Inherited Variable

The inheritedVariable element specifies a variable that SHOULD inherit its value from a variable defined in a previous level of the same IU instance. An inheritedVariable SHOULD only be defined within an IU update or within a temporary fix.

·        inheritedVariable [anonymous type]
This element does NOT specify any content. The name of this variable, as defined by the corresponding attribute, SHOULD be used to locate the corresponding persisted value associated with an existing IU instance.

 

8.1.6.1               Example

<variable name="definedInBase">

<inheritedVariable/>

</variable>

 

 

8.1.7           Scoping rules for variables

The following rules apply to variable scope and override.

1.      Variable names MUST be unique within the descriptor.

2.      The scope of a variable is the IU in which it is defined, and any inline IUs and CUs that the IU contains.

3.      Variables defined in the root IU have global scope within the descriptor. An iuDiscriminant variable defined in the root IU can be referenced only within IUs that are associated to the same target whose check definition is referenced by the variable definition.

4.      Referenced IUs have a separate namespace for variables. The only interaction is via parameter maps. An IU aggregating referenced IUs MAY use a parameter map to redefine a variable in the referenced IU.

8.2Variable Expressions

Some elements of the IUDD schema are instances of base:VariableExpression. The latter is a simple XML type derived by restriction from the XML base string type:

<simpleType name="VariableExpression">

   <restriction base="token">

       <pattern value="([^$]*($[^(])*($\([a-zA-Z_]+[0-9a-zA-Z_]*\))*)*"/>

   </restriction>

</simpleType>

The restriction forces the substring “xxxx” contained within an enclosing substring “$(xxxx)” to be a valid variable identifier, as defined by the type NCName.

The consumer of an element that is an instance of the base:VariableExpression type MUST resolve the variables in the string and substitute each “$(xxxx)” token appearing in the variable expression with the value of the corresponding variable. 

8.3 Conditional Expressions

A conditional expression MAY appear as the value of a condition attribute in the following schema elements within the IUDD:

·        An expression element, defined within the derivedVariable element of a variable definition, see Section 8.1.2;

·        An installable unit definition within the base or selectable content of the root IU, see Section 6;

·        A unit element within an SIU or CU defining an artifact set, see Section 9.3.

Conditional expressions also appear in artifacts where they are used to condition actions and action groups, see Section 14.

Check variables, property queries and derived variables based on property queries MAY be used in conditions. The use of parameters is permitted but discouraged, as a condition is intended to represent an environmental constraint and not a user selection. Resolved target lists and IU discriminant variables SHOULD NOT be used in conditions.

A condition element is an instance of base:VariableExpression, see Section 8.2. Once variable substitution has occurred in a condition, the resulting conditional expression MUST be a (constant) XPath boolean expression, with the following restrictions:

1.      When all the variable substitutions have been completed, the string value of a condition element must be a valid XPath boolean expression. The format of the XPath expressions is defined by the XML Path Language (XPath) Version 1.0 (http://www.w3.org/TR/xpath).

2.      The boolean expression to which the condition element reduces after variable substitutions SHOULD NOT contain any of the following:

·        Variables References

·        Node Sets Expressions, including functions returning a node set.

·        Function calls.

These constraints SHOULD be enforced by the tooling and validated by the installer.

8.3.1           Example

condition="('$(win_drive)' != 'C:') and ('$(win_drive)' != 'Z:')"

 

Note that string literals can appear within single quotes if the conditional expression attribute is enclosed within double quotes, and vice versa. Note that operators like “<” and “>” cannot be directly typed within the conditional expression and MUST be escaped by, for example using &lt; and &gt; respectively. Syntax details are described at http://www.w3.org/TR/xpath.

8.4 Evaluation of variables, checks and conditions

Any variable that is declared in an installable unit and which is first used in the Create or InitialConfig operations, see Section 4.2,  SHOULD have its value set during the operation in which it is first used. The value SHOULD then be saved and restored on successive lifecycle operations.

A variable declared in a configuration unit or that is declared in an installable unit and first used in the Configure operation SHOULD be re-evaluated during each Configure operation. The value MAY be saved for use on successive VerifyConfig operations.

Conditions on IUs SHOULD be evaluated during the Create or Update operation, in order to determine which IUs should be installed. Subsequent life cycle operations SHOULD NOT add or remove an installable unit based on the current evaluation of a condition.

Conditions on configuration units SHOULD be re-evaluated during each Configure and VerifyConfig operation.

All checks SHOULD be re-evaluated in any operation for which their value is needed to evaluate a requirement.

9         Software Smallest Installable Unit

This section defines the Smallest Installable Unit (SIU) of software. This is specified in the schema file siu.xsd. The aggregation of such elementary units into larger aggregates is described in Section 6.

An SIU instance is defined by the siu:SmallestInstallableUnit schema type illustrated in the following diagram.

 

The SIU definition is an instance of the above type. It includes the following attributes:

·        IUName [type=ID]
This REQUIRED attribute is an identifier of the IU element in the instance document. It SHOULD NOT be confused with the IU identity name, see Section 5.1. This attribute MAY be used to refer to the IU from other elements within the descriptor.

·        hostingEnvType [type=siu:AnyResourceType].
This OPTIONAL attribute  specifies the type of the SIU hosting environment. When specified, the value of this attribute SHOULD be equal to the one specified by the type attribute of the target onto which the SIU is installed, see Section 5.6.1. The latter is identified by the targetRef attribute of the installableUnit element defining this SIU. The IU hosting environment type may be specified to exploit tooling support for the prevention of incorrect targeting. The type of this attribute is defined as a union of the XML type QName and rtype:Rtype. Therefore, a user defined hosting environment resource type can be specified as a QName value. Standard enumerated values for resource types are defined in  rtype:Rtype. Tooling MAY constrain this attribute to known valid hosting environment types (NOT all resources are hosting environments).

 

 

 

The schema constructs IUorFixDefinition, SingleTargetIUDefinition and Variables are common to an SIU as well as to other installable unit types defined in Section 6:

• IUorFixDefinition
  This element contains information about the identity, constraints, obsoletedIUs and supersededFixes of the installable unit. This information is relevant to both single- and multi-target installable units. See Section 9.1.
• SingleTargetIUDefinition
  This element contains information specific to single-target installable units, such as signatures, checks and requirements. Signatures are described in Section 13, while the latter two elements – checks and requirements – are described in Section 7.
• Variables
  This element contains information about variables, defined within the context of the SIU. See Section 8 for a definition of variables and variable expressions. Any variable that is referenced by a variable expression within an SIU MUST be declared within the SIU. See Section 8.1.7 for a definition of variable scope. The most important use of variables, in an SIU, is in artifact parameter maps, which associate variables defined in the SIU with variables defined within the artifacts. See 9.5.

The SIU definition includes the following element in addition to the above constructs:

• unit [type=siu:InstallArtifactSet]
  At least one instance of this element MUST be specified. The content of this element defines one set of artifacts – artifacts are separately bundled descriptors for actions OR resource property definitions – associated to this SIU. Artifact sets are described in Section 9.3.
  The unit element may specify the following condition attribute:

§         condition [type=base:variableExpression]
This OPTIONAL attribute defines a condition that, controls the selection of the artifact set associated to the unit element. At most one artifact set will be selected. This attribute SHOULD NOT be specified when a single unit element is defined. The attribute MUST be specified when multiple unit elements are specified, in which case the conditions defined for each of them SHOULD be constructed so that they are mutually exclusive: if they are not, then an arbitrary selection between qualified artifact sets MAY be made.

9.1 Installable Unit Definition

The main elements of an IU definition are grouped by the siu:IUorFixDefinition XML group. The latter contains information which is applicable to both single-target and multi-target installable units: part of the elements apply to an ordinary IU while other apply to a temporary fix. The following diagram illustrates the part that applies to an ordinary IU (the part of the diagram related to a temporary fix definition is not expanded: it contains only the element fixIdentity, already defined in Section 5.2).

 

 

The identity element is defined in Section 5.1. This section describes the other elements that can be specified as part of an IU definition, namely constraints, obsoletedIUs and supersededFixes. Superseded fixes can be specified both in the context of an IU definition and in the context of a fix definition.

• constraints [anonymous type]
  This OPTIONAL element may be specified to include one or both of the following two elements:

o       maximumInstances [type=nonNegativeInteger]
This OPTIONAL element is the limit to the number of instances of the IU that can be simultaneously present onto the same instance of a target hosting environment. The number is unbounded when this element is NOT specified.

o       maximumSharing [anonymous type]
This OPTIONAL element is an instance of a complex anonymous type,  extending the XML nonNegativeInteger type. The numeric value of this element is the maximum number of IU instances that MAY have a dependency on one instance of this IU. Containment and software dependencies by other IUs in the same IUDD MUST NOT be considered. Dependencies from outside of the root IU MUST be considered. These include simple “Uses” relationships (when this IU satisfies a software dependency) as well as “Federates” relationships (when this IU satisfies a federated IU definition).
The following attribute MAY be used to further restrict the use of this IU only by instances of an identified set of IUs.

§         sharedBy_List [type=base:ListOfUUIDs]
This OPTIONAL attribute is a list of UUID values corresponding to  IUs whose instances are allowed to make shared use of this IU (within the sharing limits set by the numeric value of the element).

• obsoletedIUs [anonymous type]
  This OPTIONAL element of the IU definition consists of a sequence of one or more elements, each one defining one IUs that is made obsolete by this installable  unit. When installed in the context of an Update operation, this IU deletes the obsoleted IUs that are part of the same root IU instance. An IU SHOULD NOT declare itself obsoleted (e.g. to have an instance of a previous version removed).

o       obsoletedIU [anonymous type]
This element is used to specify the IU to be obsoleted. An obsoleted IU SHOULD be physically deleted  after installing the IU which contains the obsoletedIU declaration. Deleting obsoleted IUs at the end of the update process makes it possible to migrate configuration data that the IU may hold.  However, this implies that there should be no intersection between resources (files, objects, etc.) deployed by the obsoleted IUs and content deployed by the updating IU,  otherwise some of the new content would be uninstalled when the obsoleted IU is deleted. If multiple instances of the obsoleted IU exists within the root IU instance being updated, these SHOULD be all deleted. This elements contains an XML choice construct to select one OR the other among the following two elements:

§         UUID [type=base:UUID]
The UUID to be used to locate the obsoleted IU instances.

§         name [type=token]
The identity name of the obsoleted IU instances.

• supersededFixes [type=base:ListOfIdentifiers]
  This OPTIONAL element can be specified for both an IU and a fix definition. The type of this element is defined as an XML list of NCName typed items. Each item in the list is used to specify a value matching the name of the fix that is superseded. The fixName element is part of a fix identity and it is described in Section 5.2.
  
  Updates and temporary fixes, see Section 11, MAY consolidate the contents of a previously applied fix into their content. This information MAY be used by the change management system to determine the appropriate action to take regarding the currently installed fixes. If a fix or an update is applied that supersedes another fix, then a check for the superseded fix may be satisfied by the superseding fix. If an upgrade is applied and there are fixes on the previous level that are not superseded by the upgrade, it may be necessary to reapply those fixes.
  
  Declaring a fix as superseded SHOULD NOT require an implementation to take any action other than eliminating the IU-Fix association after the superseding IU (or Fix) has been applied  to the target IU instance. That is, fixes declared as superseded by a Fix or by an IU update are NOT REQUIRED to be rolled-back when the fix or update is installed. The assumption is that a fix (or IU update) B that supersedes a fix A must be robust enough to handle both the case in which fix A is installed and the case in which it is not installed. The system SHOULD be left in a consistent state in both cases.  See Section 11.3 for a discussion of updates to an instance with non superseded fixes.

9.1.1           IU Constraints Example

<constraints>

  <maximumInstances>1</maximumInstances>

  <maximumSharing sharedBy_List="1234567890...123456789012">100</maximumSharing>

</constraints>

The above sample XML fragment defines constraints for an IU of which there MUST be no more than one instance. It also specifies that there could be a maximum of 100 dependent instances sharing the same instance of the IU. All of these dependent IUs are instances with the specified UUID (the sharedBy_List attribute has only one element).

9.1.2           Obsoleted IUs

<obsoletedIUs>

<obsoletedIU>

        <UUID>12345678901234567890123456789000</UUID>

</obsoletedIU>

<obsoletedIU>

        <UUID>12345678901234567890123456789001</UUID>

</obsoletedIU>

<obsoletedIU>

        <name>ThisIUname</name>

</obsoletedIU>

</obsoletedIUs>

The above sample XML fragment defines three obsoleted IUs. The first two are identified by their respective UUID. The last one is identified by its name.

9.1.3           Superseded Fixes

<supersededFixes>PTF012345 PTF123456 PTF234567</supersededFixes>

The above sample XML fragment contains a declaration that three temporary fixes are superseded by the IU or fix whose definition contains the declaration.

9.2 Temporary Fix Definition

A temporary fix is an installable unit that is not part of the normal sequence of released versions. A temporary fix MAY be a root IU, or an SIU,  or any other type of installable unit that MAY be defined as part of a root IU. What makes it possible to distinguish a temporary fix from an ordinary IU is the identity. The identity of temporary fixes is described in Section 5.2.  

Any IU aggregate, including root IUs, that defines a temporary fix SHOULD only aggregate IUs that are themselves temporary fixes.

When performing an installable unit check that includes checks on temporary fixes, the check MUST list all of the required fix names. See Section 7.3.6. Although one fix may explicitly supersede another fix, there is no concept of the “latest” fix superseding all previous fixes.

A fix MAY consolidate one or more of the current temporary fixes. These are listed by the supersededFixes element, which is described in the context of an IU definition in Section 9.1.3.  

Fixes MAY be categorized, by specifying the fixType element in the fix identity.

·        fixType[anonymous type]
This OPTIONAL element may be used to specify one of the following enumerated values:

o       “InterimFix”
Tested and verified fix available to customers. It may contain fixes for one or several product defects and fixes for internally discovered defects. It is typically made available to the registered users.

o       “TestFix”
A temporary or uncertified fix with limited testing that is supplied to one or several customers for testing, but is typically not available for the general public. Typically, this type of fix has little or no packaging, i.e. may be file replacements.

o       “ProgramTemporaryFix”
An individual fix that is typically made available to all customers. A PTF resolves one customer reported problem.

9.2.1           Fix Dependencies

Two temporary fixes applying to the same single-target IU instance MAY be subject to the following relationships, which pose constraints on their installation:

·        ex-requisite
An instance SHOULD NOT have the two fixes simultaneously applied;

·        co-requisite
An instance SHOULD have the two fixes simultaneously applied OR none applied;

·        pre-requisite
This is a directional relationship. The fix declaring another fix as a pre-requisite SHOULD NOT be applied if the latter is NOT applied first.

In principle, it is possible to express the above relationships using IU checks, see Section 7.3.6. In practice, this results in complex descriptors. For this reason the fix definition includes the fixDependencies element. This element is expanded at the bottom of the following diagram, whose other elements have been described in Section 5.2.

  

 

·        fixDependencies [anonymous type]
This OPTIONAL element may be specified to include one or more of the following elements:

o       pre-requisite_fixes [type=base:ListOfIdentifiers]
This OPTIONAL element is used to specify a space separated list of fix names. Every one of the listed fixes SHOULD be applied before this temporary fix can be applied.

o       co-requisite_fixes [type=base:ListOfIdentifiers]
This OPTIONAL element is used to specify a space separated list of fix names. Every one of the listed fixes SHOULD be available to be applied with this temporary fix. The order in which the fixes are physically applied is NOT specified and it SHOULD be irrelevant. This fix and all the ones listed by this element SHOULD be applied before the updated IU achieve the usable state.

o       ex-requisite_fixes [type=base:ListOfIdentifiers]
This OPTIONAL element is used to specify a space separated list of fix names. This temporary fix SHOULD NOT be applied if any of the listed fixes is already applied to the IU being updated.

9.2.2           Fix Definition Example

      <installableUnit>

         <SIU IUName="PTF_1" hostingEnvType="OSCT:Operating_System">

            <fixIdentity>

               <name>MyPDF Reader</name>

               <UUID>12345678901234567890123456789012</UUID>

               <incremental>

                  <requiredBase>

                     <minVersion>5.0.1</minVersion>

                     <maxVersion>5.0.4</maxVersion>

                  </requiredBase>

               </incremental>

               <fixName>PTF123456</fixName>

               <fixDependencies>

                  <pre-requisite_fixes>PTF001234 PTF012345</pre-requisite_fixes>

               </fixDependencies>

            </fixIdentity>

            <unit>

               <installArtifacts>

                  <installArtifact>

                     <fileIdRef>PTF_1Actions</fileIdRef>

                  </installArtifact>

               </installArtifacts>

            </unit>

         </SIU>

      </installableUnit>

The above sample XML fragment contains a complete definition of a temporary fix SIU. The identity element defines the name and UUID of the IU  to which the fix can be applied. The fix name is “PTF123456” and it has fixes “PTF001234” and “PTF012345” as pre-requisites. The unit element describes artifacts associated to this temporary fix SIU.

9.3 Unit - Artifact Sets

The unit element in an SIU defines the artifacts to be used when performing life cycle operations on the installable unit, see Section 4.2. An artifact is a descriptor containing the definition of actions to be performed on the hosting environment, or a definition of a set of resource properties to be configured. The separation of the action definition from the declarative IU dependency information permits a supporting implementation where the IU descriptor is interpreted by a generic change management component, whereas the actions are interpreted by a hosting-environment specific component.

The above diagram illustrates the artifact sets. There are two defined sets of artifacts. The first set handles the lifecycle operations that are performed to install an IU. The second set of artifacts handles the operations to configure or reconfigure the IU.

An SIU contains one or more artifacts, each one intended for use with a specific life cycle operation. As an example, an Install artifact is needed for the Create and Update operations, while an Uninstall artifact is needed for Delete. The artifact is REQUIRED to be an XML document, but its exact content beyond that is constrained only by the hosting environment, although this specification does provide recommended formats – the Action Definition and Resource property Definition – that may be extended, see Sections 14 and 15. The intended implementation is that the appropriate artifact is passed to the hosting environment, which then uses the artifact to performing the life cycle operation.

As SIU unit is an instance of siu:InstallArtifactSet, and it describes the artifacts related to the installation of software. Units are also defined for configuration units (CU) units that are instances of siu:ConfigurationArtifactSet, describing artifacts related to configuration. This section describes the artifacts related to installation. Those related to configuration are described in Section 10.

The type siu:InstallArtifactSet is illustrated in the following diagram.

 

 

The following OPTIONAL elements are instances of siu:UndoableArtifact – which  is an extension of the base type siu:Artifact, defined in Section 9.5,  including the following attribute:

o       undoable [type=boolean]
This OPTIONAL attribute – default is “false” –  is used to identify whether the associated life cycle operation can be performed in an “Undo” mode. Where supported, an undoable operation supports a rollback operation, where the installable unit is rolled-back to its state prior to applying the operation. An implementation SHOULD support at least the Update operation in “Undo” mode An implementation MAY support only a single level of undoable Update, in which case it MAY automatically commit a previous level.
The artifact types described by each one of the elements illustrated in the above diagram are described in the Section 9.4 below. 

 

·        installArtifact [type=siu:UndoableArtifact].
This OPTIONAL element SHOULD define an Install artifact.  

·        initialConfigArtifact [type=siu:UndoableArtifact]
This OPTIONAL element SHOULD define an InitialConfig artifact.

·        migrateArtifact [type=siu: UndoableArtifact]
This OPTIONAL element SHOULD define a Migrate artifact.

The following OPTIONAL elements are instances of the siu:Artifact type, described in Section 9.5

·        verifyInstallArtifact [type=siu:InstallArtifact]
This OPTIONAL element SHOULD define a VerifyInstall artifact.

·        uninstallArtifact [type=siu:InstallArtifact]
This OPTIONAL element SHOULD define an Uninstall artifact.

 

9.4 Install Artifacts and IU Lifecycle Operations

Artifacts are either applied to a hosting environment to implement a software life-cycle operation; or they are applied to a manageable resource to set or to verify a specified configuration. Artifacts of the first type will be generally referred to as “install artifacts”, while artifacts of the second type will be referred to as “configuration artifacts”.

Install artifacts are part of the definition of a Smallest Installable Units (SIU) while configuration artifacts are part of the definition of a Configuration Unit (CU). Note that there are no artifacts associated with an IU aggregate.

 

Artifact type	Description
Install	If the install artifact is associated to a base SIU (or a full update SIU, see Section 11.1) it can be used by the Create operation to create an instance of the SIU. If the artifact is associated to an update (full or incremental) or to a fix, it can be used by the Update operation to install the update (or the fix) to an existing instance of the required base SIU.  A software instance is initially created and then it is possibly modified by successive update operations, each one applying the install artifact associated to an update or fix SIU. Actions defined in the install artifact MAY refer to bundled files provided with the packaged solution. Access to the bundled files referenced by the install artifact is only supported by the Create, Update and Repair operations. Other operations that MAY access the install artifact (Delete, Undo, VerifyIU) do NOT have access to the referenced bundled files. Other artifacts MUST NOT contain references to bundled files.
InitialConfig	The initialConfig artifact is used only for a base or a full update SIU, see Section 11.1. A fix or an SIU defining an incremental update MUST NOT specify an initialConfig artifact. The artifact defines actions that are needed to bring a newly created IU instance in the Usable state. When this artifact is specified, the Create operation leaves a newly created instance  in the “Created” state, to indicate that a successive InitialConfig operation is needed to bring the instance to the Usable state. Otherwise, the newly created instance transitions directly to the Usable state. Actions defined in the initialConfig artifact MUST NOT contain references  to bundled files.
Migrate	The artifact defines actions that are needed to configure an updated IU instance. The migrate artifact is used only for a full update or an incremental update. A fix or an SIU that cannot be used to upgrade a base instance MUST NOT specify a migrate artifact. When this artifact is specified, the Update operation leaves a modified instance in the “Updated” state, to indicate that a successive Migrate operation is needed to bring the instance to the Usable state. Otherwise, the updated instance transitions directly to the Usable state. Actions defined in the migrate artifact MUST NOT contain references  to bundled files.
VerifyInstall	The verifyInstall artifact is used by the VerifyIU operation to perform integrity checking of an SIU instance. On some hosting environments the VerifyIU operation MAY process the install artifacts successively applied to the instance by updates and fixes. Access to the actions defined by the install artifact for creating or updating the SIU instance may be exploited to identify resources, created as part of the SIU instance, that need to be verified. As the SIU instance may have passed through multiple updates, the VerifyIU MAY need to examine multiple install artifacts. Some hosting environments MAY allow the SIU definition of the verifyInstall artifact to be a reference to the SIU install artifact. In that case, the VerifyIU operation SHOULD use the install artifact to identify the resources (e.g. files) created as part of the install that need to be verified. Actions defined in the verifyInstall artifact MUST NOT contain references to bundled files.
Uninstall	The uninstall artifact is used by the Delete operation to perform the removal of an SIU or fix. An update or fix that does not introduce new resources as part of an existing instance (only modifies pre-existing resources) SHOULD NOT specify an uninstall artifact. On some hosting environments the Delete operation MAY process the install artifacts successively applied to the instance by updates and fixes. Access to the actions defined by the install artifact for creating or updating the SIU instance may be exploited to identify resources, created as part of the SIU instance, that needs to be removed. As the SIU instance may have passed through multiple updates, the Delete MAY require to examine multiple install artifacts in reverse order. Some hosting environments, MAY allow the SIU definition of the uninstall artifact to be actually a reference to the SIU install artifact. In that case, the Delete operation SHOULD use the install artifact to identify the resources (e.g. files) created as part of the install that need to be removed. Actions defined in the uninstall artifact MUST NOT contain references  to bundled files.

 

As illustrated in the above table, a single artifact can be accessed in the context of different IU lifecycle operations. The following table lists the primary artifact accessed by each operation.

 

Lifecycle Operation	Artifact Type
Create	Install artifact
InitialConfig	InitialConfig artifact
Update	Install artifact
Migrate	Migrate artifact
Delete	[Uninstall artifact] [Install  artifact]
VerifyIU	[VerifyInstall artifact] [Install  artifact]
Repair	[Install artifact]
Undo	[Install  artifact]

 

Note that the Undo operation MAY need to access the install artifact to roll-back the last update applied to an instance, but that MAY NOT be required on all hosting environments. Analogously, the Repair operation MAY NOT need to access the install artifacts of the IU instance being repaired. An artifact type between square brackets, in the above table, MAY NOT be accessed by the corresponding operation.

9.5 Artifact

The type siu:Artifact, illustrated by the following diagram, is the base type for all artifacts defined within an artifact set.

The only REQUIRED content of an artifact definition, within the IUDD, is a reference to a bundled file containing the actual artifact. The latter is itself a descriptor of variables and actions or properties that MAY contain references to other bundled files.

An artifact definition has the following attributes:

·        HE_restart_required [type=boolean]
This OPTIONAL attribute – default is “false” – specifies  whether a hosting environment restart (in case of an operating system hosting environment this would correspond to a reboot) is REQUIRED after processing the actions in the artifact. See Section 9.5.1.

An artifact definition has the following elements:

·        fileIdRef [type=IDREF]
This REQUIRED element is used to identify the bundled file containing the artifact (XML descriptor). The value MUST be a valid reference to a bundled file, see Section 5.8.

·        type [type=siu:ArtifactFormat]
This element is OPTIONAL. The assumed value, if the element is NOT specified, is “ActionDefinition”. The type of this element is a union of siu:StandardArtifact Format and NCName, where the former enumerates the names of two standard artifact formats. Any value in the range of NCName MAY be assigned to the element to specify a user-defined artifact format.
The standard enumerated values are:

o       “ActionDefinition”.
See Section 14 for a definition of the proposed format for artifacts of this type.

o       “ResourcePropertiesDefinition”.
See Section 15 for a definition of the proposed format for artifacts of this type.

·        parameterMaps [type=base:Maps]
This OPTIONAL elements maps variable names in the descriptor to variable names that are meaningful in the context of the hosting environment. The use of these variables is hosting-environment specific. These MAY be used to initialize variables defined within the artifact, see Section 14, OR they MAY be used directly by the hosting environment. In particular, some of the external variable names, in these maps, MAY identify variables that have a special meaning to the hosting environment (e.g. install path). Each map element can be used to specify the following elements:

o       internalName [type=IDREF]
This REQUIRED element is a reference to a variable defined within the IUDD whose value is used to initialize a corresponding artifact variable identified by the externalName element.

o       externalName [type=NCName]
This REQUIRED element is used as a reference to avariable defined within the artifact that MUST be initialized with the value of the IUDD variable identified by the internalName element.

The map element also includes an attribute – direction – that can be used to specify a reverse mapping where the value of an artifact variable is used to set an IUDD variable. The default value of this attribute (“in”)  is appropriate for an SIU or CU artifact, as it corresponds to the above stated semantic of the internalName and externalName mapping. A different value (“out”) can be only specified for a check artifact (see Section 7.3.8). In other terms, there is no provision for variables to be set as a result of executing a SIU or CU artifact.

9.5.1           Declarative Hosting Environment Restart

A restart of the hosting environment runtime, e.g. an operating system reboot,   SHOULD NOT be directly invoked by actions in the artifact. The need for a restart of the hosting environment MAY be indicated using the HE_restart_required attribute (default “false”) in the artifact definition. If this attribute is set to “true”, the hosting environment SHOULD be restarted after processing of the artifact has been completed.

The restart is NOT conditioned to the occurrence of specific conditions  (e.g. the presence of locked files on an operating system hosting environment). However, the restart MAY be postponed until after further IUs within the same life cycle operation have also been processed within the same hosting environment, provided that none of the IUs with a pending restart are required as pre-requisites.

A pre-requisite IU MUST be brought to the Usable state by performing the pending restart before other dependent installable units can be installed.

In some cases it is possible and preferable to determine the need for a restart while the target hosting environment is processing the artifact. In order to support this capability, a hosting environment MAY provide interfaces – that actions supported within an artifact MAY leverage – to notify the need if a restart. After notification, the restart would be properly sequenced with other pending operations. In that case the requirement for restart SHOULD NOT be normally declared in the artifact definition.

10   Configuration Unit

A configuration unit (CU) is an atomic unit of configuration. Like an SIU, a CU can be specified as part of an aggregated installable unit. The following differences exist between a configuration unit and an SIU:

·        A CU does NOT have a unique identity and does not represent a distinct entity with a defined lifecycle (e.g. that might be recorded in a registry).

·        Configuration units can be targeted NOT only to hosting environments, but also to any type of managed resource.

·        The life cycle operations applying configuration units to the target managed resources are described in Section 4.3.

A configuration unit is an instance of siu:ConfigurationUnit, the type illustrated in the following diagram.

 

A configuration unit has the following attributes: 

• CUName [type=ID]
  This REQUIRED attribute is an identifier of the CU definition within the IUDD. This attribute MAY be used to refer to the CU from other elements within the descriptor. It does NOT provide a persistent global identifier.
• resourceType [type=siu:AnyResourceType]
  This REQUIRED attribute is used to specify the resource type of the CU target managed resource. The type of this attribute is defined as a union of the XML type QName and rtype:RType. Therefore, a user defined resource type can be specified as a QName value. Standard enumerated values for this field are defined in  rtype:Rtype.

 

A configuration unit has the following elements: 

 

• displayName [type=base:DisplayElement]
  This OPTIONAL element allows to associate text labels and a description with the corresponding CU. See Section 17 for a general description of display elements and their localization.

·        manufacturer [type=base:DisplayElement]
This OPTIONAL element allows to specify the name and description of the CU manufacturer. See Section 17  for a general description of display elements and their localization.

• checks [type=siu:CheckSequence]
  This OPTIONAL element includes a sequence of checks, see Section 7.1.
  
  
• requirements [anonymous type]
  This OPTIONAL element includes a sequence of requirements, see Section 7.2.
  
  
• variables [anonymous type]
  This OPTIONAL element includes a sequence of variables, see Section 8.1.
  
  
• unit
  This REQUIRED element defined the configuration artifact set for the CU. Artifact sets are introduced in Section 9.3. This element is an instance of siu:ConfigurationArtifactSet, described in Section 10.1 below.

10.1 Configuration Artifact Set

The type siu:ConfigurationArtifactSet is illustrated in the following diagram.

 

The following OPTIONAL elements are instances of the type siu:Artifact, defined in Section 9.5. The artifacts described by each one of the elements illustrated in the above diagram are described in the Section 10.2 below. 

·        configArtifact [type=siu:Artifact].
This OPTIONAL element SHOULD define a Configure artifact.  

·        verifyConfigArtifact [type=siu:Artifact]
This OPTIONAL element SHOULD define a VerifyConfig artifact.

 

Each one of the above artifact declarations MAY include information on its format through the OPTIONAL type element. Standard enumerated values, see Section 9.5, are:

·        “ActionDefinition”
The artifact defines actions to be executed on a target hosting environment. This format MAY be appropriate for a  CU that configures an IU instance through its hosting environment.
See Section 14 for a definition of the proposed format for artifacts of this type.

·        “ResourcePropertiesDefinition”
The artifact defines property values. This  is the preferred format to define the configuration of a manageable resource.
See Section 15 for a definition of the proposed format for artifacts of this type.

10.2 Configuration Artifacts and IU life cycle

The artifacts described in the following table are applied to a manageable resource to set or to verify a specified configuration.

 

Artifact type	Description
Configure	The configure artifact is associated to a CU and it defines actions to configure a resource. The artifact is processed by the Configure operation acting on a manageable resource. Actions defined in the configure artifact MUST NOT contain references to bundled files.
VerifyConfig	The verifyConfig artifact is used by the VerifyConfig operation to verify the configuration of a manageable resource. Actions defined in the verifyConfig artifact MUST NOT contain references to bundled files.

 

11   Temporary Fixes and Updates

Both fixes and updates are considered to be a form of installable unit, which can occur at any level of aggregation, including as a root IU. Fixes and updates follow a hierarchy that must match the hierarchy of the original root IU, so that a consistent set of rules applies to both fixes and updates.

Only one  fix can be defined within an update or fix root IU for each inline IU in the base. Specifically, only one  fix per SIU can be defined. The fixName element (see Section 5.2) identifying a fix aggregate IU logically represents all fixes applied to any of the aggregated children IUs[6].

A fix aggregate IU applying to an aggregate in the base that included a referenced or federated IU, may include multiple fixes[7] for that referenced or federated IU. The order of applying multiple fixes to the same referenced IU is determined by sequence numbers or by fix dependencies.

 

Figure 11: Fixes and updates in an aggregated IU

 

Figure 11 illustrates the use of fixes and updates. An offering X, consisting of two components A and B, is shipped at Version 5.0.0 and deployed as a fresh install. A subsequent update to X is shipped at version 5.0.1. It contains an incremental update to both A and B, and fixes which apply to those incremental updates.

If an aggregating IU contains an update to a child IU, then that aggregating IU must also be updated. However, a root IU MAY be independently installed and it MAY be federated by multiple aggregating IUs. Fixes and updates applied to the federated IU outside of the context of an aggregating IU would NOT be reflected as an update (version change) of the aggregating IU. This process, MAY cause the dependencies of the aggregating IU to be invalidated, if the dependencies specify a maximum version for the federated IU: an implementation of the deployment system may warn if this is the case. A similar situation MAY occur when a federated IU is updated as part of an aggregated IU, and is also shared by another aggregated IU.

Installable units are categorized as "Full" or "Incremental". A full IU always has a unique version number, and MAY either be a base install, which installs a new version of a product; or an upgrade, which MAY either install a new version, or upgrade an existing a version to a new version.  The remainder of this section considers only incremental IUs, and Full IUs that can be applied as updates.

An incremental update IU MAY contain only the subtrees of its original content containing the modified SIUs. An incremental update MAY also introduce new IUs and fixes. It MAY specify that certain IUs have been “obsoleted” and are no longer needed.

A full update MAY totally replace the previous version of the installable unit. Since a full IU MAY be installed independently of an existing base, it MUST include all the content that is part of the required base and that is NOT being obsoleted.

A full IU MUST aggregate only full IUs, or full IUs plus updates and fixes to those IUs. It MUST NOT aggregate an update or fix on its own. However, it MAY contain fixes and updates as bundled requisites.

An incremental update IU MAY aggregate full IUs, update IUs and fixes. However, for each one of the aggregated updates or fixes, the IUs to which these are applied MUST be defined in the IUDD of the base root IU. Each one of these updates or fixes is applied to a corresponding IU instance within the root IU instance being updated. In particular, the update process relies on the restriction stated in Section 6 that an aggregate IU cannot have two children with the same UUID, to associate each IU update to a single instance of its required base that is located within the corresponding aggregation level within the updated root IU, see Section 12.5.1.

A fix is a form of incremental update, but SHOULD only aggregate other fixes.

Characteristics of the fix/update support include:

·        It is possible to place requirements on a fix at the SIU or CIU level.

·        Fixes and updates are applied in a given context (within their aggregating IU).

·        A set of fixes for a solution can be provided, that are to be installed together.

·        In-line IUs within a solution cannot be updated by fixes for the same IU in another solution[8].

Elements of the identity definition for installable units are described in Section 5.1. In particular, one of the two elements illustrated in the following diagram MAY be specified to indicate whether the IU is an update to another base IU. When no elements are specified, the IU is assumed by default to be a “full” IU with no upgrade base.

 

 

 

• full [anonymous type]
  When specified, this element declares the IU to be a full IU, which requires no pre-existing upgrade base to be installed. The following elements further qualify the nature of the full IU.
• • upgradeBase [type=base:requiredBase]
    This OPTIONAL element indicates that the full IU MAY be applied as an upgrade to an existing base. It also defines the range of prior versions to which this IU MAY be applied as an update. The following elements define the version range:
  • • minVersion [type=vsn:VersionString]
      This OPTIONAL element defines the minimum required version.
    • maxVersion [type=vsn:VersionString]
      This OPTIONAL element defines the maximum required version.
  • type [anonymous type]
    This OPTIONAL element can be use to categorize full IUs. The value can assume one of the following enumerated values:
  • • “BaseInstall”
      A deliverable that contains the initial release of a product.
    • “ManufacturingRefresh”
      A deliverable that is a product replacement, containing all previously delivered maintenance plus, optionally, new fixes not delivered previously. This type of update may be provided as new media, and may be packaged to install as an upgrade or as a new install. It may apply to one or multiple products but can only apply to one release of a product or bundle of products. It optionally may not contain fixes previously shipped that have been found to be in error and have not yet been fixed by available maintenance. If it contains new function, other than any small new function (such as a new device driver) already contained in a previously shipped fix that is included in this Manufacturing Refresh, then "M" in V.R.M SHOULD be incremented
    • “RecommendedServiceUpgrade”
      Cross product tested recommended service upgrade (RSU). A cross product/component consolidated, tested, and recommended set of service to a platform (or multi-platforms for distributed). Contains all latest product/component interim fixes (distributed), fix packs, PTFs, and refresh packs. Any previously shipped fixes may not be included in an RSU if they have been found in error and a correcting fix is not yet available when the RSU is built. If new function is included in a RSU, then "M" in V.R.M SHOULD be incremented.
      
      
      
• incremental [anonymous type]
  When specified, this element declares the IU to be an “incremental” update, that MAY only be applied to an existing update base. The following elements further qualify the nature of the full IU.
• • updateBase [type=base:requiredBase]
    This REQUIRED element defines the range of prior versions to which this IU can be applied as an update. This element is an instance of the same type – base:RequiredBase – discussed above for the upgradeBase element of a full IU.
  • type [anonymous type]
    This OPTIONAL element can be use to categorize incremental updates. The value can assume one of the following enumerated values:
  • • “FixPack”
      A fix pack is cumulative, i.e. contains all the fixes shipped in previous maintenance to the release including previous fix packs. Contains all fixes made to the original V.R.M. (i.e. 5.0.0) delivery or to the most recent manufacturing refresh/refresh pack (cumulative deliverable applying to one V.R.M., i.e. 5.0.1). MAY be applied on top of any previously shipped maintenance to bring the system up to the current fix pack level. It MAY include additional fixes not previously shipped. It MAY span multiple products or components.
    • “RefreshPack”
      Same definition as fix pack, but a refresh pack also contains new function. The deliverable SHOULD increment the "M" of V.R.M.
    • “CriticalFixPack”
      Similar to fix pack except that this deliverable consists of a collection of selected fixes (test fixes, interim fixes, etc.) which are usually fixes of defects with high severity.
    • “DeltaFixPack”
      Similar to fix pack except this deliverable is not cumulative since GA, refresh pack, or manufacturing refresh.
    • “CriticalDeltaFixPack”
      Similar to a delta fix pack except that this deliverable consists of a collection of selected fixes (test fixes, interim fixes, etc) which are usually fixes of defects with high severity.
      
      

Elements of the identity definition for temporary fixes are defined in Section 5.2. In particular, the element incremental/requiredBase is an instance of base:RequiredBase and it defines the admissible version range for the IU to which the fix can be applied.

11.1 Full update use for Create and Update

A full IU can be used to create a new instance (fresh install) or to upgrade an instance of the associated upgrade base. Therefore, the descriptor of a full update IU can be used by the Create and the Update operations. During the Update operation it MUST be possible to identify IUs, including aggregates, that are already defined in the base descriptor and that SHOULD NOT be installed as part of the update.

A full IU specifying an upgrade base SHOULD declare obsoleted all IUs in the base  that are not represented in the full IU descriptor[9].  When used as an update, the full IU establishes a new base, i.e. the history of previous updates applied to an existing IU instance in the upgrade base that is not obsoleted SHOULD be ignored. The IUDD of the full IU and its associated artifacts are used for the life cycle management of any IU instance that is part of the updated root IU after the update.

It is recommended that an update descriptor use the same IUName internal identifier for IUs that are also defined in the base descriptor. If the same IUName internal identifier is used in an update, it SHOULD apply to the corresponding IU in the base. However, there is no requirement to be able to associate the IUName internal identifier with an installed IU instance. As a result, identification of the IU instances MUST be based on UUID.

The following constraint MUST be imposed on IUDD documents to support the above identification method:

An aggregate IU CANNOT include two sibling IUs that have the same UUID. 

With the above restriction, identification can proceed top-down from the root IU. When corresponding aggregates have the same version no update is required. Otherwise, for any IU definition in the current aggregate level, the following alternatives may occur:

·        An IU found in the update descriptor does not have a UUID match with an IU instance in the corresponding level within the root IU instance being updated.  The IU represents new content that MUST be deployed as part of the update, either because:

o       although defined in the base IUDD, the IU was not selected in the base due to different feature selections or conditions; OR

o       this is a new IU introduced in the update IUDD.

The Create operation is performed to create an instance of the new child IU.

·        For the IUs that have a UUID match, the version must be compared:

o       A matching version means that an IU was already deployed as part of the base, hence nothing needs to be done.

o       When an instance with a lower version is found, the corresponding IU in the update MAY be an update (or fix) to the base instance OR it MAY be a new base that obsoletes the current instance. An Update, or a Delete followed by a Create is performed, depending on which one of the above occurs.

o       An instance with an equal or higher version may be found when this is a federated IU that has been updated outside of the context of this aggregating IU. In that case, no update is required.

 

The IU descriptor of a full update may include CUs within aggregates that are also part of the upgrade base, as well as CUs that belong to new aggregates. When the full IU is applied as an update to an existing instance, it causes CU definitions to be reset, i.e. the CUs that are associated in the full IU to an aggregate that already exists in the base SHOULD replace the old ones and constitute a new base for CUs in that aggregate.

By contrast, CUs defined within an incremental update are simply added to the ones already defined for a corresponding aggregate of the base. An aggregate IU that is an incremental update SHOULD NOT contain a CU with the same CUName internal identifier of a CU defined in the corresponding base IU. If one such CU is defined, the definition SHOULD be ignored – it SHOULD NOT be interpreted as a definition superseding the CU definition in the base. 

11.2 Requirements checking on updates

The sub-set of topology targets specified for the base root IU that are targeted by updates MUST be defined in the topology element of the update root IU. The target “id” attribute, see Section 5.6.1, is used to associate targets in the update with targets in the base. The topology in the update IU MAY include also additional targets, associated to new features. Any IU within the update root IU that defines an update to a base IU must be associated to the same target.

Selection requirements of a target declared in the topology section of the base SHOULD be omitted in the descriptor of an incremental update. If specified, they SHOULD be ignored.    

11.2.1      Target instances selected for the update

An update is deployed onto the target instances that were selected during install of the base: a candidate target instance that was not selected when the base IU was deployed SHOULD not be targeted by the update. Different implementations may have different methods to determine the range of target instances where the base IU was installed and onto which the update can be applied.

An updated IU – or a new IU that is part of the update – MAY introduce new requirements to be satisfied on a topology target. For example, a new service pack needs to be installed on an operating system target. However, it SHOULD be possible to satisfy the new requirements on all instances of the target that were selected when the base instance was created. This can be achieved for new software requirements by specifying the canBeSatisfiedBy clause in the check.

Requirements on the target that are introduced by a new or updated IU MAY be declared in that IU OR they MAY be defined as additional validation requirements on the corresponding target.

11.2.2      Reference to variables in the base IU descriptor

The value of a variable defined within the descriptor of the base IU may have been passed through a parameter map for use by actions defined in the install artifact. The actions in the install artifact of an update IU MAY need this information in order to implement the update in a consistent manner.  Therefore, it SHOULD be possible to access the value of a variable defined in a previous level.

Variables defined by an IU and used during install SHOULD retain their value across operations (see 8.4). Moreover, variables defined within multiple updates of the same IU MUST share the same namespace:

·        a specific variable declaration – inheritedVariable – can be used within an update to create a reference to a variable declared in some previous level, including the base level (see Section 8.1.6). 

·        a variable name SHOULD NOT be reused in a new level other than via inheritedVariable. The behavior is undefined if the variable name is re-used, although some implementations MAY detect the error.

11.2.3      Updating dependencies

An update or fix SHOULD contain a complete definition of its requirements.

Therefore it is expected that some requirements would duplicate the same already expressed in the IU descriptor of the update base.  While it is a good practice to use the same internal identifiers for checks, requirements and alternatives that have a correspondence with the ones declared in the update base, this is NOT required.

An update or fix MAY have more stringent requirements on a software dependency (i.e. a dependency associated to a software or an IU check) that was also declared in the base IU. In that case the update MAY include bundled requisite IUs to satisfy those requirements.

An example is as follows. An update is required to IU “B” because of an update being applied to another IU “A”, on which “B” depends. It is desired to ship both updates in a single root IU, in order to apply updates to both IUs at the same time. The synchronized update of an IU and its dependencies can be specified as follows:

·        the check specified by IU “B_UPD” (update to B) identifies the software dependency by the same UUID (and/or name) and a newer version;

·        a bundled requisite IU containing “A_UPD” (update to A) is specified by the canBeSatisfiedBy element of the check.

When installing the update, the requisite SHOULD only be applied to upgrade an instance that is already in use by the base IU.

 

<iu checkId="A_check_in_Bupdate">

<UUID>12345678901234567890123456789012</UUID>

<minVersion>8.1.1</minVersion>

<canBeSatisfiedBy>bundled_A_FixPack</canBeSatisfiedBy>

</iu>

11.2.4      Requirements with multiple alternatives

An implementation of the Update operation needs to ensure that, in presence of software dependencies declared in multiple alternatives of a requirement, the same instance of an external software dependency is selected that is already in use by the base. See Section 7.2 for a definition of requirements with alternatives.

To facilitate this, the following assertion is made:

One IU MUST NOT have a dependency on more than one IU instance with a given UUID or name.

If an IU update declares a software dependency to an IU with the same UUID (or name) as a dependency already satisfied in the base, the same instance already in use SHOULD be selected. Because of the above assumptions, the following process can be applied to the evaluation of alternatives for each requirement declared in the IU update:

·        Software dependencies that are in use by the IU instance being updated are identified;

·        Any software dependency within an alternative that