AgentRef (ATG Java API)

java.lang.Object
- atg.deployment.server.AgentRef

All Implemented Interfaces:

atg.deployment.common.Constants, atg.deployment.DeploymentConstants
```
public class AgentRef
extends java.lang.Object
implements atg.deployment.common.Constants
```
The server-side reference to a remote deployment agent. The server agent-ref has key information about the deployment for the server and houses the actual transport implementation for communicating with the agent. Though the Target object will most likely be all that is required, the AgentRef reveals a finer granularity of information about the target.
The AgentRef contains information from the topology definition file for this agent:
- name
- hasDeploymentResponsibilities
- principalAssets
- excludeAssetDestinations
- includeAssetDestinations
- transportType
- transactionSize
The AgentRef is mostly an informational object but does give access to initializing and reinitializing the AgentTransport used to speak with the remote agent this AgentRef represents. The methods initializeTransport() and reinitializeTransport() are used respectively for these tasks, but should not necessarily need to be called as higher level methods should take care of this.
The methods getState() and getStatus() provide information on the specific agent whereas Target.getStatus() combines the statuses returned from a list of agents.

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String CLASS_VERSION
Class version string

java.util.Map mAgentHostLocalPortCache
- Fields inherited from interface atg.deployment.common.Constants
  ACCEPTED_FOR_TARGET, APPLY_TRANSACTION_SIZE, APPROVED_FOR_TARGET, DEPLOYED_TO_TARGET, DEPLOYMENT_PROTOCOL_VERSION, DEPLOYMENT_TYPE_BACK_DEPLOY, DEPLOYMENT_TYPE_DEPLOY_TO_INITIAL, DEPLOYMENT_TYPE_INIT_TARGET, DEPLOYMENT_TYPE_ONE_OFF_DEPLOY, DEPLOYMENT_TYPE_REVERT_DEPLOY, DEPLOYMENT_TYPE_STANDARD_DEPLOY, DPLY_CMD_ACTIVE_APPLY_COMMITTED, DPLY_CMD_AFFECTED_TYPES, DPLY_CMD_ASSET_DESTINATIONS, DPLY_CMD_CLUSTER_ID, DPLY_CMD_COMMAND, DPLY_CMD_DATASTORES_TO_SWITCH, DPLY_CMD_DEPLOYMENT_END_TIME, DPLY_CMD_DEPLOYMENT_ID, DPLY_CMD_DEPLOYMENT_START_TIME, DPLY_CMD_EXCLUDE_ASSET, DPLY_CMD_FIRST_APPLY, DPLY_CMD_FROM_SNAPSHOT, DPLY_CMD_INCLUDE_ASSET, DPLY_CMD_INSTALL_BYTES, DPLY_CMD_INSTALL_NUM_BYTES, DPLY_CMD_MODE, DPLY_CMD_ONEOFF, DPLY_CMD_PRINCIPAL, DPLY_CMD_PROJECTS, DPLY_CMD_PROTOCOL_VERSION, DPLY_CMD_RECOVERING, DPLY_CMD_REFRESH_REPOSITORIES, DPLY_CMD_RESUME, DPLY_CMD_ROLLBACK, DPLY_CMD_SCIEVENTS, DPLY_CMD_SERVER_NAME, DPLY_CMD_SET_AGENT_STATUS, DPLY_CMD_SWITCH_FIRST, DPLY_CMD_SWITCH_LIVE, DPLY_CMD_TO_SNAPSHOT, DPLY_CMD_TYPE, DPLY_CMD_USER_ID, DPLY_CMD_VERIFY_FILE_CHECKSUM, DPLY_CMD_VERIFY_FILE_COMPONENT_PATH, DPLY_CMD_VERIFY_FILE_LAST_MODIFIED, DPLY_CMD_VERIFY_FILE_PATH, DPLY_CMD_VERIFY_FILE_SIZE, DPLY_CMD_VFS_ORDER, HIDDEN_FROM_TARGET, INIT_BRANCH_LOCK_NAME, ONE_OFF, REMOTE_DYNAMIC_RELOAD_EXCEPTION, REMOTE_DYNAMIC_RELOAD_SUCCESS, REMOTE_SWITCH_EXCEPTION, REMOTE_SWITCH_SUCCESS, RENOUNCED_FOR_TARGET, ROLLBACK_DEPLOYMENT_FAILURE, STRICT_OP_DEFAULT, STRICT_OP_OVERRIDE_FALSE, STRICT_OP_OVERRIDE_TRUE, TARGET_INITIAL_STATE_PROJECT_ID, TOPOLOGY_AGENT_PRINCIPAL_ALL, TOPOLOGY_AGENT_PRINCIPAL_NONE, TOPOLOGY_AGENT_PRINCIPAL_REPOSITORY, TOPOLOGY_AGENT_PRINCIPAL_VFS, TOPOLOGY_DEPLOY_TYPE_ONE_OFF, TOPOLOGY_DEPLOY_TYPE_WORKFLOW, TOPOLOGY_TRANSPORT_JNDI, TOPOLOGY_TRANSPORT_RMI, WORKFLOW
- Fields inherited from interface atg.deployment.DeploymentConstants
  DEPLOYABLE_ATTRIBUTE_NAME, DEPLOYMENT_SYSTEM_VERSION, EXPORT_ATTRIBUTE_NAME, IMPORT_ATTRIBUTE_NAME, JAR_ATTR_MAN_FILE, JAR_ATTR_MAN_ID, JAR_ATTR_VERSION, MODE_ONLINE, MODE_SWITCH, PM_DEP, REFERENCES_ATTRIBUTE_NAME, TYPE_FULL, TYPE_INCREMENTAL

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`CLASS_VERSION` Class version string
`java.util.Map`	`mAgentHostLocalPortCache`

Constructor Summary

Constructors
Modifier Constructor and Description

protected AgentRef()
Constructor for testing only.

Constructors
Modifier	Constructor and Description
`protected`	`AgentRef()` Constructor for testing only.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Status`	`abortApply(java.lang.String pDeploymentID)` Tells the agent to abort the application.
`Status`	`cancelDeployment(java.lang.String pDeploymentID)` Tells the agent to cancel the deployment.
`void`	`deleteDeployedSnapshotId()` Delete the deployed snapshot id from the cluster status for this agent.
`Status`	`doneCreate(java.lang.String pDeploymentID, java.util.Map pAffectedTypes)` Notifies the agent of the affected item types for a particular deployment via a Map with a key of affected repository path names to a Set value of affected item types.
`java.util.Collection`	`getAllClusterStatus()` Wrapper call to the AgentTransport for this agent.
`java.lang.String`	`getClusterID()`
`Status`	`getCurrentStatus()` Wrapper call to AgentTransport.getStatus() for this agent.
`java.util.Map`	`getDestinationMap()` Mapping from source VFS destination to target VFS destination.
`java.lang.String[]`	`getExcludeAssetDestinations()` Specific asset destinations this agent is not to deploy.
`java.lang.String`	`getHostnameAndLocalPort(java.lang.String pSeperator)` Get hostname and local port for local FileDeploymentServer connections seperated by the given Seperator string
`java.lang.String`	`getId()` Unique id of this deployment agent.
`java.lang.String[]`	`getIncludeAssetDestinations()` Specific asset destinations this agent is to deploy.
`java.lang.String`	`getName()` Name of this deployment agent.
`java.lang.String[]`	`getPrincipalAssets()` Asset types which this agent is responsible for deploying.
`int`	`getState()` Wrapper call to the AgentTransport for this agent.
`Status`	`getStatus()` Wrapper call to AgentTransport.getStatus(clusterID) for this agent.
`Status`	`getStatus(boolean pUseCache)` Wrapper call to AgentTransport.getStatus(clusterID) for this agent.
`java.lang.String`	`getTransportType()` Returns the transport type used by this agent, the same type used in the XML topology definition file.
`java.lang.String`	`getTransportURI()`
`boolean`	`hasDeploymentResponsibilities()` Returns whether or not this Agent has deployment responsibilities.
`boolean`	`initializeTransport()` If the transport failed to start up properly more attempts can be made until the transport starts.
`java.util.List`	`mapDestinations(java.util.List pDestinations)` Maps any destinations that change name from the source-side name to the target-side name
`java.util.Map`	`mapDestinations(java.util.Map pDestinations)` Maps any destinations that change name from the source-side name to the target-side name.
`java.lang.String[]`	`mapDestinations(java.lang.String[] pDestinations)` Maps any destinations that change name from the source-side name to the target-side name
`Status`	`recoverAgent(java.lang.String pDeploymentID, java.util.Map pRecoverInfo)` Recover the agent for the deployment.
`boolean`	`reinitializeTransport()` Destroys the current transport and initializes a new one.
`boolean`	`reinitializeTransport(Status pErrorStatus)` Destroys the current transport and initializes a new one.
`Status`	`setAgentStatus(java.lang.String pDeploymentID, java.util.Map pToStatus)` Sets the agent's Status remotely from the Publishing server to the specified Status
`Status`	`setClusterDestination(java.util.Set pClusterDestinations)`
`void`	`setClusterID(java.lang.String pClusterID)`
`Status`	`switchDatastores(java.util.List pDatastores)` Requests a switch of the specified datastores on this agent server.
`Status`	`verifyFile(java.lang.String pComponentPath, java.lang.String pFilePath, long pChecksum, long pFileSize, long pLastModified)` Check if a file deployed to this agent has the given checksum, size and last modified date This operation can happen outside of a deployment so no deployment id is required.

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
  - mAgentHostLocalPortCache
```
public java.util.Map mAgentHostLocalPortCache
```
- Constructor Detail
  - AgentRef
```
protected AgentRef()
```
    Constructor for testing only.
- Method Detail
  - getId
```
public java.lang.String getId()
```
    Unique id of this deployment agent.
    
    Returns:
    
    String
  - getName
```
public java.lang.String getName()
```
    Name of this deployment agent.
    
    Returns:
    
    String
  - getPrincipalAssets
```
public java.lang.String[] getPrincipalAssets()
```
    Asset types which this agent is responsible for deploying. Values will only be those allowed in the topology file.
    
    Returns:
    
    String[]
  - getExcludeAssetDestinations
```
public java.lang.String[] getExcludeAssetDestinations()
```
    Specific asset destinations this agent is not to deploy.
    
    Returns:
    
    String[]
  - getIncludeAssetDestinations
```
public java.lang.String[] getIncludeAssetDestinations()
```
    Specific asset destinations this agent is to deploy.
    
    Returns:
    
    String[]
  - getDestinationMap
```
public java.util.Map getDestinationMap()
```
    Mapping from source VFS destination to target VFS destination.
    
    Returns:
    
    String[]
  - getTransportType
```
public java.lang.String getTransportType()
```
    Returns the transport type used by this agent, the same type used in the XML topology definition file. Note that JNDI would not show up here as a type since JNDI types are resolved into actual transport implementations.
    If the transport could not be initialized, the String BAD is returned.
    
    Returns:
    
    String
  - setClusterID
```
public void setClusterID(java.lang.String pClusterID)
```
    Parameters:
    
    pClusterID -
  - getClusterID
```
public java.lang.String getClusterID()
```
    Returns:
  - initializeTransport
```
public boolean initializeTransport()
```
    If the transport failed to start up properly more attempts can be made until the transport starts. This allows deployment agents who may not have fully started up to be accessed once they have started up. (Server startup order is always rough.)
    Note: This method only tries to start the transport if it did not initially start. To change an agent's transport that is already running the topology XML file needs to be changed and the entire topology re-initialized.
    
    Returns:
    
    true if after the call the transport is initialized
    false if after the call the transport is *not* initialized
  - reinitializeTransport
```
public boolean reinitializeTransport()
```
    Destroys the current transport and initializes a new one.
    
    Returns:
    
    true if the transport reinitialized properly
    false if the transport failed to initialize
  - reinitializeTransport
```
public boolean reinitializeTransport(Status pErrorStatus)
```
    Destroys the current transport and initializes a new one. The supplied error message is used to log a warning as to why the the agent transport is being re-initialized.
    
    Returns:
    
    true if the transport reinitialized properly
    false if the transport failed to initialize
  - hasDeploymentResponsibilities
```
public boolean hasDeploymentResponsibilities()
```
    Returns whether or not this Agent has deployment responsibilities. This value is based on the principalAssets and includeAssetDestinations properties.
  - getState
```
public int getState()
```
    Wrapper call to the AgentTransport for this agent. If the transport has not been initialized (or has been destroyed due to an error), an attempt will be made to initialize the transport. If the transport cannot be initialized, Status.ERROR_TRANSPORT_UNINSTANTIATED will be returned.
    
    See Also:
    
    AgentTransport
  - getStatus
```
public Status getStatus()
```
    Wrapper call to AgentTransport.getStatus(clusterID) for this agent. This returns the cluster-specific Status of the agent.
    If the transport has not been initialized (or has been destroyed due to an error), an attempt will be made to initialize the transport. If the transport cannot be initialized, a Status with state set to Status.ERROR_TRANSPORT_UNINSTANTIATED will be returned. When possible an error message will be supplied and available from Status.getErrorMessage().
    
    See Also:
    
    AgentTransport
  - getStatus
```
public Status getStatus(boolean pUseCache)
```
    Wrapper call to AgentTransport.getStatus(clusterID) for this agent. This returns the cluster-specific Status of the agent.
    If the transport has not been initialized (or has been destroyed due to an error), an attempt will be made to initialize the transport. If the transport cannot be initialized, a Status with state set to Status.ERROR_TRANSPORT_UNINSTANTIATED will be returned. When possible an error message will be supplied and available from Status.getErrorMessage().
    
    See Also:
    
    AgentTransport
  - getCurrentStatus
```
public Status getCurrentStatus()
```
    Wrapper call to AgentTransport.getStatus() for this agent. This returns the current Status of the agent, regardless of the current cluster.
    If the transport has not been initialized (or has been destroyed due to an error), an attempt will be made to initialize the transport. If the transport cannot be initialized, a Status with state set to Status.ERROR_TRANSPORT_UNINSTANTIATED will be returned. When possible an error message will be supplied and available from Status.getErrorMessage().
    
    See Also:
    
    AgentTransport
  - getAllClusterStatus
```
public java.util.Collection getAllClusterStatus()
```
    Wrapper call to the AgentTransport for this agent. If the transport has not been initialized (or has been destroyed due to an error), an attempt will be made to initialize the transport. If the transport cannot be initialized, null will be returned.
    
    See Also:
    
    AgentTransport
  - getTransportURI
```
public java.lang.String getTransportURI()
                                 throws atg.deployment.common.DeploymentException
```
    Throws:
    
    atg.deployment.common.DeploymentException
  - doneCreate
```
public Status doneCreate(java.lang.String pDeploymentID,
                         java.util.Map pAffectedTypes)
```
    Notifies the agent of the affected item types for a particular deployment via a Map with a key of affected repository path names to a Set value of affected item types.
  - abortApply
```
public Status abortApply(java.lang.String pDeploymentID)
```
    Tells the agent to abort the application.
    This usually happens because another agent in the target has failed.
  - cancelDeployment
```
public Status cancelDeployment(java.lang.String pDeploymentID)
```
    Tells the agent to cancel the deployment. If performed successfully, the agent's Status and ClusterStatus for this CA cluster should be in an IDLE state.
    
    Parameters:
    
    pDeploymentID - identifier for this deployment
    
    Returns:
    
    Status for the agent at the end of the call
  - recoverAgent
```
public Status recoverAgent(java.lang.String pDeploymentID,
                           java.util.Map pRecoverInfo)
```
    Recover the agent for the deployment.
  - setAgentStatus
```
public Status setAgentStatus(java.lang.String pDeploymentID,
                             java.util.Map pToStatus)
```
    Sets the agent's Status remotely from the Publishing server to the specified Status
  - setClusterDestination
```
public Status setClusterDestination(java.util.Set pClusterDestinations)
```
  - switchDatastores
```
public Status switchDatastores(java.util.List pDatastores)
```
    Requests a switch of the specified datastores on this agent server.
  - mapDestinations
```
public java.util.Map mapDestinations(java.util.Map pDestinations)
```
    Maps any destinations that change name from the source-side name to the target-side name. Takes a map with TOPOLOGY_AGENT_PRINCIPAL_VFS and TOPOLOGY_AGENT_PRINCIPAL_REPOSITORY. Only maps VFSs currently.
    
    Returns:
    
    the list of mapped destinations
  - verifyFile
```
public Status verifyFile(java.lang.String pComponentPath,
                         java.lang.String pFilePath,
                         long pChecksum,
                         long pFileSize,
                         long pLastModified)
```
    Check if a file deployed to this agent has the given checksum, size and last modified date This operation can happen outside of a deployment so no deployment id is required.
  - getHostnameAndLocalPort
```
public java.lang.String getHostnameAndLocalPort(java.lang.String pSeperator)
                                         throws atg.deployment.common.DeploymentException
```
    Get hostname and local port for local FileDeploymentServer connections seperated by the given Seperator string
    
    Parameters:
    
    pSeperator -
    
    Returns:
    
    Throws:
    
    atg.deployment.common.DeploymentException
  - mapDestinations
```
public java.lang.String[] mapDestinations(java.lang.String[] pDestinations)
```
    Maps any destinations that change name from the source-side name to the target-side name
    
    Returns:
    
    the list of mapped destinations
  - mapDestinations
```
public java.util.List mapDestinations(java.util.List pDestinations)
```
    Maps any destinations that change name from the source-side name to the target-side name
    
    Returns:
    
    the list of mapped destinations
  - deleteDeployedSnapshotId
```
public void deleteDeployedSnapshotId()
```
    Delete the deployed snapshot id from the cluster status for this agent.

Class AgentRef

Field Summary

Fields inherited from interface atg.deployment.common.Constants

Fields inherited from interface atg.deployment.DeploymentConstants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CLASS_VERSION

mAgentHostLocalPortCache

Constructor Detail

AgentRef

Method Detail

getId

getName

getPrincipalAssets

getExcludeAssetDestinations

getIncludeAssetDestinations

getDestinationMap

getTransportType

setClusterID

getClusterID

initializeTransport

reinitializeTransport

reinitializeTransport

hasDeploymentResponsibilities

getState

getStatus

getStatus

getCurrentStatus

getAllClusterStatus

getTransportURI

doneCreate

abortApply

cancelDeployment

recoverAgent

setAgentStatus

setClusterDestination

switchDatastores

mapDestinations

verifyFile

getHostnameAndLocalPort

mapDestinations

mapDestinations

deleteDeployedSnapshotId