atg.deployment.server
Class Deployment

java.lang.Object
  atg.deployment.server.Deployment

All Implemented Interfaces:

java.lang.Runnable

public class Deployment
extends java.lang.Object
implements java.lang.Runnable

A stateful representation of a Deployment. This class contains the deployment process and is used to monitor and control that process.

Deployment objects are created by scheduling or queueuing a new deployment through a Target instance and are only ever associated with a single target. All deployments initially go into the specific target's schedule or queue and therefore cannot be started directly. The target's queue will eventually start the deployment.

The progression of a deployment can be monitored by calling getStatus(). Alternatively, a DeploymentEventListener could be written and registered with the DeploymentServer. Such a listener will begin receiving events for a deployment once begin() is called on the deployment by the target queue.

A scheduled or queued deployment can have its deploy time changed with a simple call to setDeployTime(). Alternatively, any scheduled or queued deployment can be moved to the head of the deployment queue by calling runNext(). This is the extent of queue and schedule manipulation allowed.

Once a deployment has started successfully, the entire process will run in a separate thread. If the deployment fails or the caller needs to interrupt the deployment, stop() can be called to stop and/or reset the deployment. Likewise, any stopped deployment or any deployment that is waiting in the queue or schedule can be deleted by calling delete().

If a deployment fails, rather than stopping the deployment, either resume() or rollback() can be called to resume the deployment or roll back the target to the data set that was active before the deployment began. For example, if an agent dies but is immediately rebooted during a deployment, the process is interrupted with a network error, most likely a returned Status.ERROR_TRANSPORT. In such a situation, the calling code could wait until the Target becomes fully accessible again and then call resume() on the deployment, as in the following example:

 // Monitors the deployment till it is finished or errored on a
 // non-network error.  In the case of a network error, the
 // deployment will be resumed as soon as the target is accessible.
 public void monitorDeployment (Target pTarget)
   throws DeploymentException
   {
     // Get the current deployment and monitor it till either it
     // completes or encounters an error.
     Deployment deployment = pTarget.getCurrentDeployment();
     Status status = deployment.getStatus();
     while (status.isStateError() == false &&
            status.getState() != Status.DEPLOYMENT_COMPLETE)
       {
         // Sleep for a while using your favorite method
         // for making a thread take a nap.
         
         // Reaquire the deployment status to check it 
         // once again for completion or error.
         status = deployment.getStatus();
       }
     // The monitoring loop has been broken.  Check to see if the
     // monitoring loop was broken by an error.
     if (status.isStateError())
       {
         // Deployments do not exactly reflect that a network error
         // occurred but rather tell you in what phase of the
         // deployment an error occurred.  So although there is a
         // window where a network error could disappear, we'll look
         // to the target to find out if one caused our error.
         status = pTarget.getStatus();
         if (status.getState() == Status.ERROR_TRANSPORT ||
             status.getState() == Status.ERROR_TRANSPORT_UNINSTANTIATED)
           {
             // Yup, network error occurred (or something).  Wait until
             // the target is accessible again and then try and resume
             // the deployment.
             while (pTarget.isAccessible() == false)
               {
                 // Sleep for a while using your favorite method
                 // for making a thread take a nap.
               }
             // Now that the target is reporting as accessible, try to
             // resume the deployment and continue to monitor it.
             deployment.resume();
             // Hey look, uncontrolled recursion!  (That's bad.)
             monitorDeployment(pTarget);
           }
       }
   }
 

For special situations, if the target's deployment queue is halted Deployment.begin() can be called directly on a scheduled or queued deployment to run immediately. If there is alread a deployment occupying the role of current deployment, that deployment must be delt with before any other deployment can run, specifically it must either be allowed to finish or stopped and deleted. E.g.:

  // Halt the target's deployment queue.
  Target t = deploymentServer.getTarget("mySpecialTarget");
  t.haltQueue();
  // NOTE: If there is a running deployment we would have to decide
  // how we want to deal with it here.  (I.e. delete it or let it 
  // it complete.)
  if (t.isDeployable())
    {
      String[] ids = { "projID-0001" };
      Deployment d = t.deployProjects(ids,
                                      false, // do not force a full deploy
                                      null,  // no schedule
                                      "my-login-name");
      d.begin();
    }
 

See Also:

DeploymentServer, Target, DeploymentEventListener

Nested Class Summary

class	Deployment.ProjectMergeComparator Annoying to sort Projects for merge, so here is a Comparator.
class	Deployment.VersionContainerIncludeCheckerImpl

Field Summary

static java.lang.String

CLASS_VERSION Class version string

Method Summary

void	activateDeployment(boolean pRefreshAffectedRepositoryCaches) Tells each agent to activate the deployment.
void	agentException(int pNewCode, Status pStatus, AgentRef pAgent) Create an exception and update the deployment status based off the passed in agent information.
void	begin() Begins the deployment process.
void	delete(java.lang.String pDeleteInitiator) Deletes the this deployment from the target's list of pending deployments.
static java.util.Enumeration	find(VirtualFile file, DevelopmentLine pLine) Returns an Enumeration of all VirtualFiles at or below some file, in depth-first order.
static java.util.Enumeration	find(VirtualFile file, VirtualFilenameFilter filter, DevelopmentLine pLine) Returns an Enumeration of all VirtualFiles at or below some file, in depth-first order, which are accepted by the given filter.
AgentRef[]	getAccessibleAgents() The list of deployment agents that were last known to be accessible.
long	getBeginTimestamp() System milliseconds when the deployment began (or began again).
java.lang.String	getCreateInitiator() A generic identifier denoting who or what created/started this deployment.
java.lang.String	getDeploymentID() A generated identifier to distinguish this deployment from others.
Snapshot	getDeploymentSnapshot() Return the deployment snapshot.
java.util.Calendar	getDeployTime() The scheduled time this deployment should begin.
AgentRef[]	getInaccessibleAgents() The deployment agents in this target that are currently inaccessible.
int	getMode() The mode to be used when deploying this manifest, either MODE_ONLINE or MODE_SWITCH.
java.lang.String[]	getProjectIDs() The list of project IDs being deployed to the target.
Status	getStatus() The current status of the deployment.
Status	getStatusForUpdate() Returns the Deployment's reference to Status so that it can be updated outside of this class.
java.lang.String	getStopInitiator() A generic identifier for who or what stopped the deployment.
Target	getTarget() The target receiving the deployment.
Snapshot	getTargetSnapshot() Return the target snapshot.
java.lang.String	getTargetSnapshotID() Return the target snapshot ID.
java.lang.String	getTransferId() Returns the ID of the data transfer as used by the DataTransferAdapter.
int	getType() The deployment type represented by this manifest, either TYPE_FULL or TYPE_INCREMENTAL.
atg.versionmanager.impl.VersionContainerIncludeChecker	getVersionContainerIncludesChecker()
boolean	isForceFull() Whether or not this deployment will force a full deployment, rather than let the deployment go incrementally if possible.
boolean	isLoggingDebug()
boolean	isLoggingError()
boolean	isLoggingInfo()
boolean	isLoggingTrace()
boolean	isLoggingWarning()
boolean	isRemovable() Returns true if Target.removeDeployment() can be called for this deployment.
boolean	isResumable() Returns true if resume() can be called on this deployment.
boolean	isResume() Returns true if this is a resumed deployment.
boolean	isRevertDeployment() Whether or not this is a deployment reverting a project off of a target.
boolean	isRollbackable() Returns true if rollback() can be called on this deployment.
boolean	isStop() Returns the deployment stop flag.
boolean	isStoppable() Returns true if stop() can be called on this deployment.
java.lang.Boolean	isStrictFileOps()
java.lang.Boolean	isStrictRepoOps()
void	logDebug(java.lang.String pMessage)
void	logDebug(java.lang.String pMessage, java.lang.Throwable pThrowable)
void	logDebug(java.lang.Throwable pThrowable)
void	logError(java.lang.String pMessage)
void	logError(java.lang.String pMessage, java.lang.Throwable pThrowable)
void	logError(java.lang.Throwable pThrowable)
void	logInfo(java.lang.String pMessage)
void	logInfo(java.lang.String pMessage, java.lang.Throwable pThrowable)
void	logInfo(java.lang.Throwable pThrowable)
void	logTrace(java.lang.String pMessage)
void	logTrace(java.lang.String pMessage, java.lang.Throwable pThrowable)
void	logTrace(java.lang.Throwable pThrowable)
void	logWarning(java.lang.String pMessage)
void	logWarning(java.lang.String pMessage, java.lang.Throwable pThrowable)
void	logWarning(java.lang.Throwable pThrowable)
void	remove() Called when current deployment is being removed from the target.
void	resume() Attempts to resume/retry/restart the deployment, picking up where the deployment left off, for the most part.
void	rollback(java.lang.String pRollbackInitiator) Attempts to start a rollback deployment for this failed deployment.
void	run() Implementation of run() from the Runnable interface.
void	runNext() Moves this deployment to the head of the deployment queue.
void	setAgentStatus(java.util.Map pToStatus) Set the DeploymentAgent Status remotely from the Publishing server to the specified Status
void	setDeployTime(java.util.Calendar pDeployTime) The scheduled time this deployment should begin.
void	setLoggingDebug(boolean pLogging)
void	setLoggingError(boolean pLogging)
void	setLoggingInfo(boolean pLogging)
void	setLoggingTrace(boolean pLogging)
void	setLoggingWarning(boolean pLogging)
void	setStrictFileOps(java.lang.Boolean pStrictFileOps)
void	setStrictRepoOps(java.lang.Boolean pStrictRepoOps)
boolean	skipNonEssentialAgent(AgentRef pAgent, Status pAgentStatus) Checks to see if this agent can be skipped or not.
void	stop(java.lang.String pStopInitiator) Stops the running deployment.

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

Method Detail

getType

public int getType()

The deployment type represented by this manifest, either TYPE_FULL or TYPE_INCREMENTAL.

Returns:

int

getMode

public int getMode()

The mode to be used when deploying this manifest, either MODE_ONLINE or MODE_SWITCH.

Returns:

int

getDeploymentID

public java.lang.String getDeploymentID()

A generated identifier to distinguish this deployment from others.

Returns:

String

getTarget

public Target getTarget()

The target receiving the deployment.

Returns:

Target

getProjectIDs

public java.lang.String[] getProjectIDs()

The list of project IDs being deployed to the target.

Returns:

String[]

isForceFull

public boolean isForceFull()

Whether or not this deployment will force a full deployment, rather than let the deployment go incrementally if possible.

Returns:

boolean

setDeployTime

public void setDeployTime(java.util.Calendar pDeployTime)
                   throws DeploymentException

The scheduled time this deployment should begin. If this deployment was not scheduled for a specific time, NULL is returned.

Parameters:

pDeployTime - new value to set

Throws:

DeploymentException

getDeployTime

public java.util.Calendar getDeployTime()

The scheduled time this deployment should begin. If this deployment was not scheduled for a specific time, NULL is returned.

Returns:

Calendar

isRevertDeployment

public boolean isRevertDeployment()

Whether or not this is a deployment reverting a project off of a target. Revert deployments are created via Target.deployRevert().

Returns:

boolean true if this is a revert deployment
false if this is not a revert deployment

getStatus

public Status getStatus()

The current status of the deployment.

Returns:

Status

getStatusForUpdate

public Status getStatusForUpdate()

Returns the Deployment's reference to Status so that it can be updated outside of this class.

getBeginTimestamp

public long getBeginTimestamp()

System milliseconds when the deployment began (or began again).

Returns:

long

getCreateInitiator

public java.lang.String getCreateInitiator()

A generic identifier denoting who or what created/started this deployment.

Returns:

String

getStopInitiator

public java.lang.String getStopInitiator()

A generic identifier for who or what stopped the deployment. Null if the deployment is not stopped.

Returns:

String

getAccessibleAgents

public AgentRef[] getAccessibleAgents()

The list of deployment agents that were last known to be accessible.

Returns:

AgentRef[]

getInaccessibleAgents

public AgentRef[] getInaccessibleAgents()

The deployment agents in this target that are currently inaccessible. NOTE: An agent with deployment responsibilities is never allowed to be inaccessible.

Returns:

AgentRef[]

getTargetSnapshotID

public java.lang.String getTargetSnapshotID()

Return the target snapshot ID.

getTargetSnapshot

public Snapshot getTargetSnapshot()

Return the target snapshot.

getDeploymentSnapshot

public Snapshot getDeploymentSnapshot()

Return the deployment snapshot.

isStrictFileOps

public java.lang.Boolean isStrictFileOps()

setStrictFileOps

public void setStrictFileOps(java.lang.Boolean pStrictFileOps)

isStrictRepoOps

public java.lang.Boolean isStrictRepoOps()

setStrictRepoOps

public void setStrictRepoOps(java.lang.Boolean pStrictRepoOps)

isResume

public boolean isResume()

Returns true if this is a resumed deployment.

isStop

public boolean isStop()

Returns the deployment stop flag.

isStoppable

public boolean isStoppable()

Returns true if stop() can be called on this deployment.

This method is mainly for UIs that may or may not want to display buttons based on allowable functions due to the state of the deployment.

isResumable

public boolean isResumable()

Returns true if resume() can be called on this deployment. This method is mainly for UIs that may or may not want to display buttons based on allowable functions due to the state of the deployment.

isRollbackable

public boolean isRollbackable()

Returns true if rollback() can be called on this deployment.

This method is mainly for UIs that may or may not want to display buttons based on allowable functions due to the state of the deployment.

isRemovable

public boolean isRemovable()

Returns true if Target.removeDeployment() can be called for this deployment. This method is mainly for UIs that may or may not want to display buttons based on allowable functions due to the state of the deployment.

begin

public void begin()
           throws DeploymentException

Begins the deployment process.

begin() does some basic checks such as parameter validation, making sure no other servers are deploying to the target and then backgrounds the deployment process to another thread. begin() returns as soon as this is done. If the target cannot be locked or deployment parameters are invalid, a DeploymentException is thrown.

After begin() returns successfully, callers can only know the status of the deployment by calling Deployment.getStatus() or by registering a DeploymentEventListener with the server and listening for events for this specific deployment.

NOTE: only the target's deployment queue can call begin() on a deployment, unless the queue is halted for a special situation. Deployment thread priority can be modifed by setting the server property 'deploymentThreadPriorityDelta'.

Throws:

DeploymentException - if there is a problem starting the deployment

runNext

public void runNext()
             throws DeploymentException

Moves this deployment to the head of the deployment queue. This method can be called on any scheduled or queued deployment, i.e. any Deployment whose Status returns a state of Status.WAITING_SCHEDULED or Status.WAITING_QUEUED. After this method is called this deployment will be the one considered for deployment next by the server.

Throws:

DeploymentException - if the deployment cannot be moved in the queue

stop

public void stop(java.lang.String pStopInitiator)
          throws DeploymentException

Stops the running deployment. A stop deployment message is sent to all agents freeing them from the deployment. Manifests are *not* deleted until delete() is called.

The stop might not be immediate, as a flag must be sent to the deploying thread which will be checked on the next operation, i.e. this is not like performing an OS interrupt.

Parameters:

pStopInitiator - an identifier for who or what is stopping the deployment

Throws:

DeploymentException - if the deployment cannot be stopped or an error is encountered stopping the deployment

resume

public void resume()
            throws DeploymentException

Attempts to resume/retry/restart the deployment, picking up where the deployment left off, for the most part.

Throws:

DeploymentException - if the deployment cannot be resumed or an error is encountered restarting the deployment

rollback

public void rollback(java.lang.String pRollbackInitiator)
              throws DeploymentException

Attempts to start a rollback deployment for this failed deployment. Rollback is only applicable for incremental deployments that have committed deployment data. Before deployment data is committed, any deployment can merely be stopped (or fail) without affecting the integrity of the data on the target.

For incremental deployments that have committed deployment data, a rollback manifest is created and applied; the rollback manifest contains the operations needed to revert the target back to the pre-deployment data set.

Full deployments are too catastrophic for rollback, since all items in all data stores get deleted before data application begins. Rolling back a full deployment would essentially be doing a full deployment anyway.

Parameters:

pRollbackInitiator - an identifier for who or what is rolling back the deployment

Throws:

DeploymentException - if the deployment cannot be rolled back or an error is encountered starting the rollback deployment

delete

public void delete(java.lang.String pDeleteInitiator)
            throws DeploymentException

Deletes the this deployment from the target's list of pending deployments. If this is the current deployment, it is deletable only if Deployment.isRemovable() is true.

Parameters:

pDeleteInitiator - an identifier for who or what is deleting the deployment

Throws:

DeploymentException - if the deployment cannot be deleted

remove

public void remove()
            throws atg.deployment.common.DeploymentException

Called when current deployment is being removed from the target. Deployments that are currently running or are otherwise not safe for removal will cause a DeploymentException to be thrown.

Throws:

DeploymentException - if the deployment cannot be removed

run

public void run()

Implementation of run() from the Runnable interface. Called when the Deployment thread is started for backgrounding the deployment process. This method should not be called directly. It should only be called internally by the deployment system.

Specified by:

run in interface java.lang.Runnable

See Also:

Runnable

find

public static java.util.Enumeration find(VirtualFile file,
                                         VirtualFilenameFilter filter,
                                         DevelopmentLine pLine)

Returns an Enumeration of all VirtualFiles at or below some file, in depth-first order, which are accepted by the given filter. The filter does not "prune" directories: it can include children of an excluded directory.

find

public static java.util.Enumeration find(VirtualFile file,
                                         DevelopmentLine pLine)

Returns an Enumeration of all VirtualFiles at or below some file, in depth-first order.

skipNonEssentialAgent

public boolean skipNonEssentialAgent(AgentRef pAgent,
                                     Status pAgentStatus)

Checks to see if this agent can be skipped or not. That is, if this agent has no deployment responsibilities and encountered a transport error, it can be skipped. This method will also tell the Target to remove it from the accessible agent list.

agentException

public void agentException(int pNewCode,
                           Status pStatus,
                           AgentRef pAgent)
                    throws DeploymentException

Create an exception and update the deployment status based off the passed in agent information.

Throws:

DeploymentException

setAgentStatus

public void setAgentStatus(java.util.Map pToStatus)
                    throws DeploymentException

Set the DeploymentAgent Status remotely from the Publishing server to the specified Status

Throws:

DeploymentException

activateDeployment

public void activateDeployment(boolean pRefreshAffectedRepositoryCaches)
                        throws DeploymentException

Tells each agent to activate the deployment. After activation each agent's state should be IDLE.

Parameters:

pRefreshAffectedRepositoryCaches - If this is set to true, then deployment will notify the DeploymentAgent to refresh the caches of all affected repositories on the agent server. Otherwise, the agent server repository caches will use the default cache invalidation algorithm.

Throws:

DeploymentException

getVersionContainerIncludesChecker

public atg.versionmanager.impl.VersionContainerIncludeChecker getVersionContainerIncludesChecker()
                                                                                          throws DeploymentException

Throws:

DeploymentException

getTransferId

public java.lang.String getTransferId()

Returns the ID of the data transfer as used by the DataTransferAdapter. This is used in the Deployment UI to update the progress bar.

Returns:

the ID used by the DataTransferAdapter

isLoggingDebug

public boolean isLoggingDebug()

isLoggingError

public boolean isLoggingError()

isLoggingInfo

public boolean isLoggingInfo()

isLoggingWarning

public boolean isLoggingWarning()

logDebug

public void logDebug(java.lang.Throwable pThrowable)

logError

public void logError(java.lang.String pMessage)

logError

public void logError(java.lang.Throwable pThrowable)

logError

public void logError(java.lang.String pMessage,
                     java.lang.Throwable pThrowable)

logInfo

public void logInfo(java.lang.String pMessage)

logInfo

public void logInfo(java.lang.Throwable pThrowable)

logInfo

public void logInfo(java.lang.String pMessage,
                    java.lang.Throwable pThrowable)

logWarning

public void logWarning(java.lang.String pMessage)

logWarning

public void logWarning(java.lang.Throwable pThrowable)

logWarning

public void logWarning(java.lang.String pMessage,
                       java.lang.Throwable pThrowable)

isLoggingTrace

public boolean isLoggingTrace()

logTrace

public void logTrace(java.lang.String pMessage)

logTrace

public void logTrace(java.lang.Throwable pThrowable)

logTrace

public void logTrace(java.lang.String pMessage,
                     java.lang.Throwable pThrowable)

logDebug

public void logDebug(java.lang.String pMessage)

logDebug

public void logDebug(java.lang.String pMessage,
                     java.lang.Throwable pThrowable)

setLoggingDebug

public void setLoggingDebug(boolean pLogging)

setLoggingError

public void setLoggingError(boolean pLogging)

setLoggingInfo

public void setLoggingInfo(boolean pLogging)

setLoggingWarning

public void setLoggingWarning(boolean pLogging)

setLoggingTrace

public void setLoggingTrace(boolean pLogging)