N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide

<snapshotList> Element

The <snapshotList> element is an optional child of the <component> element. This element contains one or more named snapshot blocks. Each snapshot block provides a different way to capture the installed state of this component on the target host. One or more snapshot blocks can be used to capture different aspects of the installed state. This results in a fine-grained comparison of the captured installed state and the current state of the component. If used, this element can only appear one time.

This element has one required child element, <snapshot>, which is a named snapshot block that can be executed to capture the installed state of this component. You can use more than one <snapshot> element.

By default, a derived component inherits the accessible <snapshotList> element contents of its base component. When a derived component declares a <snapshotList>, its contents are effectively merged with those of the base component. The derived component can declare new <snapshot> elements and override inherited ones, but it cannot remove elements declared by the base component.

<snapshot> Element

The <snapshot> element is a child of the <snapshotList> element. This element defines a sequence of steps to be executed to capture the installed state this component. When a <createSnapshot> or <addSnapshot> step names this snapshot block, the steps within the prepare block are executed in order. Then, files named with the capture block are captured within the capture area of the target server. Finally, steps within the cleanup block are executed in order.

A snapshot block is also used to compare the current state of a component against its state at the time of installation. In particular, the prepare steps are re-executed on the target server. Then, files captured at install time are compared to the current state of the files, and the cleanup steps are re-executed.

The <snapshot> element has the following child elements:

If this snapshot is to be called from a <createSnapshot> step, it cannot declare any required parameters in its <paramList> element.

The <varList>, <prepare>, <capture>, and <cleanup> elements collectively define the body of the snapshot. The body is not included if the snapshot block is declared abstract.

By default, a derived component inherits all of the accessible snapshot blocks of its base component. Semantics for overriding a snapshot block are the same as those for overriding an install block.

You cannot call the base component snapshot block's prepare block from a derived component snapshot block's prepare block. This restriction applies to cleanup, as well. To make this sort of call, the base component must factor its <prepare> and <cleanup> steps into a control block that can be called by the derived component.

Attributes for the <snapshot> Element

This element has the following attributes:

<prepare> Element

The <prepare> element is a child of the <snapshot> element. This element defines a sequence of steps to prepare to capture or compare files. These steps are executed both as a result of a <createSnapshot> or <addSnapshot> step that targets this snapshot and a comparison run that targets this snapshot. In all cases, these steps are executed prior to capturing any files or performing any comparisons.

The <prepare> element children consist of one or more <call>, <execNative>, and <transform> steps. No other steps are permitted. The contained steps can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.

<capture> Element

The <capture> element defines the files and resources that are to be captured as part of this snapshot. The capture occurs only after the steps in the <prepare> block have executed. When the capture is complete, the steps in the <cleanup> block will execute.

The <capture> element children consist of one or more <addFile>, <addSnapshot>, and <addResource> elements. The files and directories that are listed in this block are captured in the order specified. The contained children can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.

<addFile> ELEMENT

The <addFile> element is a child of the <capture> element and specifies a file that is to be captured as part of the containing snapshot.

ATTRIBUTES FOR THE <addFile> ELEMENT

The <addFile> element includes the following attributes:

  • path A required attribute that specifies the path name of a file or directory on the file system of the target host. This attribute can reference simple substitution variables.

  • ownership An optional attribute that specifies the ownership option for the captured file.

    One aspect of the installed state that is captured by the snapshot is file and directory ownership. This ownership is not the same as UNIX permissions. The ownership is more closely tied to the concept of reference counts. Specifically, a file or directory can be captured as being owned by one or more snapshots.

    If the file owner later changes as a result of another component installation, this change can be recognized and reported when the file is compared against its initial state. This feature helps to track down differences that result from one component unintentionally overwriting files associated with another component. Snapshot ownership information is captured in a repository on the target host, which is known as the owners table.

    The values of the ownership attribute have the following semantics:

    • SET_SELF When the ownership is set in this way, the owners table is updated to contain a single entry for the associated file or directory. That entry lists the executing installed component and snapshot as owners. The entry also lists the capture area ID of the captured contents of the file or directory.

    • ADD_SELF When the ownership is set in this way, the installed component and snapshot are added as additional owners and share the existing capture area ID as the previous owners.

    • ADD_TEMP This value is like ADD_SELF except that a new capture is always created and its ID is always used for the new entry rather than sharing the ID of the other owners.

    If this attribute is omitted, the default value is SET_SELF.

  • filter An optional attribute of type boolean that describes whether to capture files, directories, or both.

    If the value of path is a directory, this attribute is used to indicate whether the directory itself, the files it contains, or both should be captured. If the value of path is not a directory, this attribute is ignored and the file is captured directly. If this attribute is omitted, the default BOTH is used.

    The values for this attribute are as follows:

    • DIRECTORIES

    • FILES

    • BOTH

  • recursive An optional attribute that indicates whether subdirectories should be recursively captured by using the current filter settings.

    If the value of path is a directory, this attribute indicates whether subdirectories should be recursively captured by using the current filter settings. If the value of path is not a directory, this attribute is ignored and the file is captured directly. The default value is true.

  • displayName An optional attribute that is a string to be included in the display when this snapshot entry is compared against another.

    This attribute can reference simple substitution variables.

<addSnapshot> ELEMENT

The <addSnapshot> element denotes that an external snapshot block should be executed and that its contents should be added to this snapshot.

Using an <addSnapshot> step is semantically equivalent to all of the following scenarios:

  • Adding the <prepare> steps of the called snapshot to the end of the calling snapshot's prepare block

  • Adding the <cleanup> steps of the called snapshot to the start of the calling snapshot's cleanup block

  • Adding the <capture> steps of the called snapshot to the calling snapshot's capture block in place of the <addSnapshot> step

Make sure that the files that are referenced by the called and calling snapshot blocks do not conflict.

Any number of <addSnapshot> steps can appear within a <capture> element. The called snapshot itself can contain any number of <addSnapshot> steps within its <capture> element.

When files are added to a snapshot indirectly by using <addSnapshot> callouts, the topmost component that initiated the snapshot capture is considered to be the owner of the files, as opposed to the component that contained the <addFile> directive. Similarly, when a comparison is performed on a snapshot, only <diff> element <ignore> directives of the topmost component that initiated the snapshot are considered. The <diff> element <ignore> directives that are contained on components visited as a result of <addSnapshot> callouts are not considered.

The <addSnapshot> element has one required attribute of type entityName, blockName, which is the name of the external snapshot block to execute.

The <addSnapshot> element has the following child elements:

  • <argList> An optional element that is a list of arguments to pass to the snapshot block. This element can only appear one time.

  • Installed component targeter – An optional element that identifies the component that contains the snapshot block. If this element is omitted, <thisComponent> is used.

<addResource> ELEMENT

The <addResource> element denotes a resource that is associated with the component that is to be captured as part of the containing snapshot. This element can only be included in simple components.

This element serves as a syntactic shorthand for an equivalent <addFile> element, as follows:

  • If the associated resource is a directory resource with deployMode=ADD_TO, <addResource> is equivalent to the following statement:


    <addFile path="path-of-deployed-directory" filter="FILES"
    displayName="resourceSourcePath"/>
  • If the associated resource is a directory resource with deployMode=REPLACE, <addResource> is equivalent to the following statement:


    <addFile path="path-of-deployed-directory"
    displayName="resourceSourcePath"/>
  • Otherwise, the associated resource is a file-based resource, and <addResource> is equivalent to the following statement:


    <addFile path="path-of-deployed-file"
    displayName="resourceSourcePath"/>

<cleanup> Element

The <cleanup> element is a child of the <snapshot> element and defines a sequence of steps to be executed after a file capture or comparison has completed. These steps are executed both as a result of a <createSnapshot> or <addSnapshot> step that targets this snapshot and a comparison run that targets this snapshot. In all cases, these steps are executed after capturing all files or performing comparisons. Use cleanup blocks to remove any temporary files that are created by the prepare block.

The <cleanup> element children consist of one or more <call>, <execNative>, and <transform> steps. No other steps are permitted. The contained steps can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.