The Utility interface allows you to manage the Application Controller utilities (Shell, Copy, and Archive) programmatically.
Note
Be sure to name your utilities carefully. If you create a new utility that has the same name as a running utility, an error is issued. However, if there is an existing utility with the same name that is not running, the new utility overwrites it.
The Utility interface consists of the following methods:
Starts the backup operation of the Archive utility.
Backup operations create an archive directory from an existing directory. The archive directory has the same name as the original directory, but with a timestamp appended to the end. The timestamp reflects the time when the backup operation was performed.
For example, if the original directory is called logs and was backed up on October 11, 2008 at 8:00 AM, the backup operation creates a directory called logs.2008_10_11.08_00_00.
Note
Do not start a backup or rollback operation while another such operation is in progress on the same directory. Unexpected behavior may occur if you do so.
RunBackupType parameters:
token identifies the token used to stop the utility or to get its status. If you do not specify a token, one is generated and returned when you start the utility.
hostID is a unique identifier for the host. The hostID and dirName parameters specify the path to the directory that will be archived.
dirName is the full path of the directory. The hostID and dirName parameters specify the path to the directory that will be archived.
numBackups specifies the maximum number of archives to store. This number does not include the original directory itself, so if numBackups is set to 3, you would have the original directory plus up to three archive directories, for a total of as many as four directories. The default numBackups is 5.
Throws:
Returns:
Launches the Copy utility, which copies files either on a single machine or between machines.
token identifies the token used to stop the utility or to get its status. If you do not specify a token, one is generated and returned when you start the utility.
fromHostID is a unique identifier for the host from which you are copying.
toHostID is a unique identifier for the host to which you are copying.
sourcePath is a string representing the file, wildcard, or directory to be copied. A sourcePath must start with an absolute path, such as C:\ or /. A sourcePath can contain . or .. as directory names, and expands * and ? wildcards. Note the following:
You cannot use the wildcard expressions .*, .?, or ..* as directory or file names.
Bracket wildcards, such as file[123].txt, are not supported.
destinationPath is the full path to the destination file or directory. destinationPath must be an absolute path, and no wildcards are allowed.
The destination directory must exist, unless the parent of the destination already exists and you are copying only one thing.
recursive, when true, indicates that the Copy utility recursively copies any directories that match the wildcard.
If recursive is false, the Copy utility does not copy directories, even if they match the wildcard. Instead, it creates intermediate directories required to place the copied files at the destination path.
Throws:
Returns:
Rollback operations roll back the directory to the most recent backed up version.
For example, say you have a directory called logs, one called logs.2008_10_11.08_00_00, and other, older versions. When you roll back, the following things happen:
Note
There can only be a single .unwanted directory at a time. If you roll back twice, the .unwanted directory from the first rollback is deleted.
Note
Do not start a backup or rollback operation while another such operation is in progress on the same directory. Unexpected behavior may occur if you do so.
RunRollbackType parameters:
token identifies the token used to stop the utility or to get its status. If you do not specify a token, one is generated and returned when you start the utility.
hostID is a unique identifier for the host. The hostID and dirName parameters specify the path to the directory that will be archived.
dirName is the full path of the directory. The hostID and dirName parameters specify the path to the directory that will be archived.
Throws:
Returns:
The startShell() method launches the Shell utility, which allows you to run arbitrary commands in a host system shell.
Throws:
Returns:
Takes a token returned by any of the start methods, and stops that invocation by terminating the process that is running it.
FullyQualifiedUtilityTokenType parameters:
Throws:
Takes a token returned by any of the Utility start methods (startBackup(), startFileCopy(), startRollback(), or startShell()), and returns the current status of that utility.
Throws:
Returns:
Performs a list operation similar to UNIX ls on a remote host, with the following restrictions on the input file pattern.
A filePattern must start with an absolute path, such as C:\ or /.
A filePattern can contain . or .. as directory names, and expands * and ? wildcards.
A filePattern cannot contain the wildcard expressions .*, .?, or ..* as directory or file names.
Bracketed wildcards, such as file[123].txt, are not supported.
You cannot use .. to create paths that do not exist. For example, the path /temp/../../a.txt refers to a path that is above the root directory. This is an invalid path that causes the operation to fail.
ListDirectoryContentsInputType parameters:
Throws:
Returns:
