atg.svc.agent.environment
Class EnvironmentMonitor

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.svc.agent.environment.EnvironmentMonitor

All Implemented Interfaces:

atg.naming.NameContextBindingListener, atg.naming.NameContextElement, atg.naming.NameResolver, atg.nucleus.AdminableService, atg.nucleus.logging.ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, atg.nucleus.logging.VariableArgumentApplicationLogging, atg.nucleus.naming.ComponentNameResolver, atg.nucleus.Service, atg.nucleus.ServiceListener, java.util.EventListener

Direct Known Subclasses:

C2CServiceEnvironmentMonitor, ServiceEnvironmentMonitor

public abstract class EnvironmentMonitor
extends atg.nucleus.GenericService

This class provides the main interface for applications to participate in monitoring and changing the agent's working environment objects.

Using an EnvironmentMonitor, applications can monitor changes made by other application and also make changes of their own that can be monitored by other applications.

Changes to the environment are applied in the following steps:

Identifying the initial change.

Each type of change that can be made to the environment has a specific string key to identify it. For example, changeUser, changeTicket or startNewCall.

Each application monitor is called back whenever a change is initiated. During this step, each monitor can add any initial EnvironmentChangeDetail objects to identify changes that will take place as a result.

A single EnvironmentChangeDetail object is used to identify a change to a single environment object.

Creating the dependent change detail objects EnvironmentChangeDetail

Each application is notified of each initial change detail object that was created in order that they may create any dependent change details. This process of creating dependent change details and notifying the monitors continues until no additional change details are created by the participating monitors.

Creating warnings

Prior to actually applying the changes, each monitor can generate warnings related to the pending changings. When changes are initiated using the EnvironmentChangeFormHandler, these warnings must be acknowledged by the agent before the changes are applied.

Applying the changes

To apply the changes to the environment, each monitor is called to apply the changes to the environment based on the change key and change details.

Reverting changes

To avoid partial changes being applied to due EnvironmentExceptions or the transaction being rolled back, each monitor that successfully applied changes up until the error is called to revert their changes through this interface so the environment state can remain consistent and as it was before the change was applied.

Field Summary

static java.lang.String	CLASS_VERSION Class version string
protected EnvironmentTools	mEnvironmentTools

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

EnvironmentMonitor()

Method Summary

abstract void	applyChanges(EnvironmentChangeState pEnvironmentChangeState) This method is called back to apply the changes detailed in the state.
void	createWarningsForEnvironmentChange(EnvironmentChangeState pEnvironmentChangeState) This method is called back to create warnings related to the changes detailed in the state.
void	generateChangeDetails(EnvironmentChangeState pEnvironmentChangeState, EnvironmentChangeDetail pEnvironmentChangeDetail) Adds EnvironmentChangeDetail objects triggered by callbacks about changes to the environment.
protected abstract void	generateChangeDetailsForChangeKey(java.lang.String pChangeKey, EnvironmentChangeState pEnvironmentChangeState) This method is called to generate the initial change details for the given change key.
protected abstract void	generateDependentChangeDetails(EnvironmentChangeDetail pEnvironmentChangeDetail, EnvironmentChangeState pEnvironmentChangeState) This method is called to generate change details that result from the given EnvironmentChangeDetail.
atg.agent.events.AgentMessagingTools	getAgentMessagingTools() Returns component for sending agent messages
abstract java.lang.Object	getEnvironmentObject(java.lang.String pEnvironmentObjectName) This method should be implemented to return the environment objects exposed by the environment monitor.
EnvironmentTools	getEnvironmentTools()
void	initializeDefaultsForProfile(atg.repository.MutableRepositoryItem pProfile) This method is called back to initialize a new profile for the environment.
void	postApplyChanges(EnvironmentChangeState pEnvironmentChangeState) This method is called back when applying changes to the environment.
void	preApplyChanges(EnvironmentChangeState pEnvironmentChangeState) This method is called back when applying changes to the environment.
void	revertChanges(EnvironmentChangeState pEnvironmentChangeState) This method is called back when the transaction is rolled back during the apply process.
void	setAgentMessagingTools(atg.agent.events.AgentMessagingTools pAgentMessagingTools) Sets the component for sending agent messages
void	setEnvironmentTools(EnvironmentTools pEnvironmentTools)

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static final java.lang.String CLASS_VERSION

Class version string

See Also:

Constant Field Values

mEnvironmentTools

protected EnvironmentTools mEnvironmentTools

Constructor Detail

EnvironmentMonitor

public EnvironmentMonitor()

Method Detail

setAgentMessagingTools

public void setAgentMessagingTools(atg.agent.events.AgentMessagingTools pAgentMessagingTools)

Sets the component for sending agent messages

Parameters:

pAgentMessagingTools -

getAgentMessagingTools

public atg.agent.events.AgentMessagingTools getAgentMessagingTools()

Returns component for sending agent messages

Returns:

AgentMessagingTools

getEnvironmentTools

public EnvironmentTools getEnvironmentTools()

Returns:

the environment tools component

setEnvironmentTools

public void setEnvironmentTools(EnvironmentTools pEnvironmentTools)

generateChangeDetails

public void generateChangeDetails(EnvironmentChangeState pEnvironmentChangeState,
                                  EnvironmentChangeDetail pEnvironmentChangeDetail)
                           throws EnvironmentException

Adds EnvironmentChangeDetail objects triggered by callbacks about changes to the environment.

Each EnvironmentChangeDetail represents a change to a single environment object. There can be only one detail per environment object in the state.

This callback routine is generates the EnvironmentChangeDetail objects relative to a specific change in the environment, like changing the current ticket.

There's two ways this method is called. It's either with or without a contextual EnvironmentChangeDetail. The EnvironmentChangeState is constant.

At the beginning of the change process, this method is called once without the contextual EnvironmentChangeDetail. In this case, applications respond to the change key in the EnvironemtChangeState and create the initial change detail objects. For example, when changing the current customer, the initial change detail is created by the framework that represents a change of customer.

After the initial set of change details are created, the monitors are called back again for each new change detail that was added in the initial pass to generate any dependent change details. This process goes on until no more new change details are added by the application monitors.

This method calls two other methods depending on whether it's called with a change detail.

Throws:

EnvironmentException

See Also:

generateChangeDetailsForChangeKey(String, EnvironmentChangeState), generateDependentChangeDetails(EnvironmentChangeDetail, EnvironmentChangeState)

generateChangeDetailsForChangeKey

protected abstract void generateChangeDetailsForChangeKey(java.lang.String pChangeKey,
                                                          EnvironmentChangeState pEnvironmentChangeState)
                                                   throws atg.svc.agent.environment.EnvironmentChangeDetailConflict,
                                                          EnvironmentException

This method is called to generate the initial change details for the given change key.

Applications should extend this method to react to framework level or custom environment change keys.

Parameters:

pChangeKey -

pEnvironmentChangeState -

Throws:

atg.svc.agent.environment.EnvironmentChangeDetailConflict

EnvironmentException

generateDependentChangeDetails

protected abstract void generateDependentChangeDetails(EnvironmentChangeDetail pEnvironmentChangeDetail,
                                                       EnvironmentChangeState pEnvironmentChangeState)
                                                throws atg.svc.agent.environment.EnvironmentChangeDetailConflict,
                                                       EnvironmentException

This method is called to generate change details that result from the given EnvironmentChangeDetail.

Parameters:

pEnvironmentChangeDetail -

pEnvironmentChangeState -

Throws:

atg.svc.agent.environment.EnvironmentChangeDetailConflict

EnvironmentException

preApplyChanges

public void preApplyChanges(EnvironmentChangeState pEnvironmentChangeState)
                     throws EnvironmentException

This method is called back when applying changes to the environment. It is called once prior to calling the applyChanges method.

EnvironmentExceptions thrown by the monitors in the preApplyChanges method will result in the change being aborted.

This is a noop impl.

Parameters:

pEnvironmentChangeState -

Throws:

EnvironmentException

See Also:

EnvironmentTools.applyChanges(EnvironmentChangeState)

applyChanges

public abstract void applyChanges(EnvironmentChangeState pEnvironmentChangeState)
                           throws EnvironmentException

This method is called back to apply the changes detailed in the state.

EnvironmentExceptions thrown by the monitors in the applyChanges method will result in the transaction being marked for rollback and each monitor that was called to apply to be called again through the revertChanges interface to revert their changes.

Parameters:

pEnvironmentChangeState -

Throws:

EnvironmentException

See Also:

EnvironmentTools.applyChanges(EnvironmentChangeState), revertChanges(EnvironmentChangeState)

revertChanges

public void revertChanges(EnvironmentChangeState pEnvironmentChangeState)

This method is called back when the transaction is rolled back during the apply process. Implement this method if the EnvironmentMonitor needs to revert changes that may already have been successfully applied.

Parameters:

pEnvironmentChangeState -

See Also:

EnvironmentTools.applyChanges(EnvironmentChangeState)

postApplyChanges

public void postApplyChanges(EnvironmentChangeState pEnvironmentChangeState)
                      throws EnvironmentException

This method is called back when applying changes to the environment. It is called once after calling the applyChanges method.

EnvironmentExceptions thrown by the monitors in the postApplyChanges method will be logged but will not cause a revert of the change and the remaining monitors will still have their postApplyChanges method called.

Note: Monitors should not execute code that could cause a transaction roll back in postApplyChanges as it could lead to an inconsistent state in the application. This is a noop impl.

Parameters:

pEnvironmentChangeState -

Throws:

EnvironmentException

See Also:

EnvironmentTools.applyChanges(EnvironmentChangeState)

createWarningsForEnvironmentChange

public void createWarningsForEnvironmentChange(EnvironmentChangeState pEnvironmentChangeState)
                                        throws EnvironmentException

This method is called back to create warnings related to the changes detailed in the state.

Generated warnings should be added to the given EnvironmentChangeState

Parameters:

pEnvironmentChangeState -

Throws:

EnvironmentException

See Also:

EnvironmentChangeState.addWarnings(List),

This is a noop implementation.

initializeDefaultsForProfile

public void initializeDefaultsForProfile(atg.repository.MutableRepositoryItem pProfile)
                                  throws EnvironmentException

This method is called back to initialize a new profile for the environment. This is a noop implementation.

Parameters:

pProfile -

Throws:

EnvironmentException

getEnvironmentObject

public abstract java.lang.Object getEnvironmentObject(java.lang.String pEnvironmentObjectName)
                                               throws EnvironmentException

This method should be implemented to return the environment objects exposed by the environment monitor.

Parameters:

pEnvironmentObjectName -

Returns:

environment object for the given name

Throws:

EnvironmentException