org.rhq.core.util.updater
Class Deployer

java.lang.Object
  org.rhq.core.util.updater.Deployer

public class Deployer
extends Object

This deploys a bundle of files within a zip archive to a managed directory. This follows rpm-like rules when updating a deployment and files already exist in previous deployments that need to be re-installed in an updated deployment. The rules are as follows, where the first three columns represent a file's hashcode:

ORIGINAL	CURRENT	NEW	What To Do...
X	X	X	New file is installed over current*
X	X	Y	New file is installed over current
X	Y	X	Current file is left as-is
X	Y	Y	New file is installed over current*
X	Y	Z	New file is installed over current, current is backed up
none	?	?	New file is installed over current, current is backed up
X	none	?	New file is installed
?	?	none	Current file is backed up and deleted

(*) denotes that the current file could have been left as-is. If, in the future, we can provide Java with a way to change file permissions or ownership, we would want to copy the new file over the current file and perform the chown/chmod. Here you can see that there is only one non-trivial case where the new file is not installed, and that is when the original file and the new file have the same hashcode (i.e. was not changed) but the current version of that file was changed (in the trivial case, where there is no new file, nothing is installed and the current file is uninstalled). In this case, since the original file and the new file are identical, the file with the modifications made to the original version (called the "current" version) is presumed to still be valid for the new version, thus we leave the current, modified file in place. In the case where there is ambiguity as to what the right thing to do is, the current file is backed up prior to being overwritten with the new file. This can occur in two cases: the first is when the current file is a modified version of the original and the new file is different from the original; the second is when there was no original file, but there is now a current file on disk and a new file to be installed. In either case, the current file is backed up before the new file is copied over top the current file. Files that need to be backed up will have its backup copied to new deployment's metadata directory, under the backup subdirectory called DeploymentsMetadata.BACKUP_DIR. If a file that needs to be backed up is referred to via an absolute path (that is, outside the destination directory), it will be copied to the DeploymentsMetadata.EXT_BACKUP_DIR directory found in the metadata directory.

Author:

John Mazzitelli

Constructor Summary

Deployer(DeploymentData deploymentData)
Constructors that prepares this object to deploy content to a destination on the local file system.

Method Summary

void	checkDiskUsage() This will get an estimate of how much disk space the deployment will need and compare it to the amount of estimated disk space is currently usable.
FileHashcodeMap	deploy(DeployDifferences diff) Convienence method that is equivalent to deploy(diff, false).
FileHashcodeMap	deploy(DeployDifferences diff, boolean clean, boolean dryRun) Deploys all files to their destinations.
FileHashcodeMap	dryRun(DeployDifferences diff) Convienence method that is equivalent to deploy(diff, true).
DeploymentDiskUsage	estimateDiskUsage() Returns an estimated amount of disk space the deployment will need if it gets installed.
DeploymentData	getDeploymentData()
boolean	isDestinationDirectoryManaged()
FileHashcodeMap	redeployAndRestoreBackupFiles(DeployDifferences diff, boolean clean, boolean dryRun) This will first perform a deploy (e.g.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Deployer

public Deployer(DeploymentData deploymentData)

Constructors that prepares this object to deploy content to a destination on the local file system.

Parameters:

deploymentData - the data needed to know what to do for this deployment

Method Detail

getDeploymentData

public DeploymentData getDeploymentData()

Returns:

information about the particular deployment that this deployer will install.

isDestinationDirectoryManaged

public boolean isDestinationDirectoryManaged()

Returns:

true if the deployer is to install the deployment data in a directory that already has a managed deployment in it. false if there is currently no managed deployments in the destination directory.

deploy

public FileHashcodeMap deploy(DeployDifferences diff)
                       throws Exception

Convienence method that is equivalent to deploy(diff, false).

Throws:

Exception

See Also:

#deploy(DeployDifferences, boolean)

dryRun

public FileHashcodeMap dryRun(DeployDifferences diff)
                       throws Exception

Convienence method that is equivalent to deploy(diff, true).

Throws:

Exception

See Also:

#deploy(DeployDifferences, boolean)

deploy

public FileHashcodeMap deploy(DeployDifferences diff,
                              boolean clean,
                              boolean dryRun)
                       throws Exception

Deploys all files to their destinations. Everything this method has to do is determined by the data passed into this object's constructor. This method allows one to ask for a dry run to be performed; meaning don't actually change the file system, just populate the diff object with what would have been done. The caller can ask that an existing deployment directory be cleaned (i.e. wiped from the file system) before the new deployment is laid down. This is useful if there are ignored files/directories that would be left alone as-is, had a clean not been requested. Note that the clean parameter is ignored if a dry run is being requested.

Parameters:

diff - this method will populate this object with information about what changed on the file system due to this deployment

clean - if true, the caller is telling this method to first wipe clean any existing deployment files found in the destination directory before installing the new deployment. Note that this will have no effect if dryRun is true since a dry run by definition never affects the file system.

dryRun - if true, the file system won't actually be changed; however, the diff object will still be populated with information about what would have occurred on the file system had it not been a dry run

Returns:

file/hashcode information for all files that were deployed

Throws:

Exception - if the deployment failed for some reason

redeployAndRestoreBackupFiles

public FileHashcodeMap redeployAndRestoreBackupFiles(DeployDifferences diff,
                                                     boolean clean,
                                                     boolean dryRun)
                                              throws Exception

This will first perform a deploy (e.g. deploy(diff, clean, dryRun)) and then, if there are backup files from the previous deployment, those backup files will be restored to their original locations. This is useful when you want to "undeploy" something where "undeploy" infers you want to go back to how the file system looked previously to a subsequent deployment (the one this method is being told to "redeploy"), including manual changes that were made over top the previous deployment. For example, suppose you deployed deployment ID #1 and then the user manually changed some files within that #1 deployment. Later on, you deploy deployment ID #2 (which will not only deploy #2's files but will also backup the files that were manually changed within deployment #1). You find that deployment #2 is bad and you want to revert back to how the file system looked previously. You could opt to rollback to deployment ID #1 minus those manual changes - to do this you simply deploy #1 again. However, if you want to go back to the previous content including those manual changes, you first deploy #1 and then restore the backup files - essentially overlaying the manual changes over top #1 files. This method accomplishes that latter task.

Parameters:

diff - see deploy(DeployDifferences, boolean, boolean)

clean - see deploy(DeployDifferences, boolean, boolean)

dryRun - see deploy(DeployDifferences, boolean, boolean)

Returns:

see deploy(DeployDifferences, boolean, boolean)

Throws:

Exception - if either the deployment or backup file restoration failed

estimateDiskUsage

public DeploymentDiskUsage estimateDiskUsage()
                                      throws Exception

Returns an estimated amount of disk space the deployment will need if it gets installed.

Returns:

information on the estimated disk usage

Throws:

Exception - if cannot determine the estimated disk usage

checkDiskUsage

public void checkDiskUsage()
                    throws Exception

This will get an estimate of how much disk space the deployment will need and compare it to the amount of estimated disk space is currently usable. If there does not appear to be enough usable disk space to fit the deployment, this method will thrown an exception. Otherwise, this method will simply return normally. This can be used to fail-fast a deployment - there is no need to process the deployment if there is not enough disk space to start with.

Throws:

Exception - if there does not appear to be enough disk space to store the deployment content