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:
<paramList> – An optional element that is a list of parameters to be used by the prepare, capture, and cleanup blocks of this snapshot. This element can only appear one time.
<varList> – An optional element that is a list of local variables to be used by the prepare, capture, and cleanup blocks of this snapshot. This element can only appear one time.
<prepare> – An optional element that contains steps to be executed in preparation for the file capture or comparison. This element can only appear one time.
<capture> – An optional element that contains a list of files and directories to be captured as part of this snapshot. This element can only appear one time.
<cleanup> – An optional element that contains steps to be executed after the capture or comparison has completed. This element can only appear one time.
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.
This element has the following attributes:
access – An optional attribute of type accessEnum, which specifies the accessibility of the snapshot block. The following values are permitted:
PUBLIC – Access is unrestricted, which is the default.
PROTECTED – Access is limited to derived components and entities that are in the same path.
PATH – Access is limited to entities that are in the same path.
PRIVATE – Access is limited to this component.
modifier – An optional attribute of type modifierEnum, which specifies the override requirements for the snapshot block. The following values are permitted:
ABSTRACT – The block cannot include a body because it must be specified by nonabstract derived components. Snapshot blocks can only be declared abstract if the component is also declared abstract. Abstract blocks cannot be private. Nonabstract blocks must declare a body.
FINAL – The snapshot block cannot be overridden by derived components.
If this attribute is omitted, derived components can choose whether to override the block.
name – A required attribute of type entityName, which is the name of the snapshot block. The name must be unique among all snapshot blocks in the containing <snapshotList>.
description – An optional attribute that is a string that describes the snapshot block. This attribute is useful for documentation purposes.
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.
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.
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.
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.
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.
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"/> |
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.