HandlerCallContext

java.lang.Object
- com.filenet.api.engine.HandlerCallContext

```
public abstract class HandlerCallContext
extends java.lang.Object
```
A HandlerCallContext object can be used for the following purposes:
- Communications between synchronous event handlers or change preprocessor handlers that execute within the same operation chain. An operation chain occurs in these scenarios:
  - when an operation on one object with an associated handler triggers an operation on a second object that also has an associated handler, such as a cascading delete.
  - when a synchronous handler acting in response to an operation on one object carries out an operation on a second object.
  Note: Operations that cause handlers to execute can be initiated by an application RPC or a background sweep job. For application RPC's that submit a batch of changes, each top-level change within the batch is treated as the root of a new operation chain, and so causes a unique HandlerCallContext to be created.
  
  For inter-handler communications, the HandlerCallContext object uses a Map object. Key/value pairs are stored in a map for retrieval by other handlers (handlers executing within the same operation chain). The handlers which interact within an operation chain retrieve the shared map. The values stored and passed in the map are defined by the participating handlers. Key/value pairs can be set or retrieved using the standard Java Map methods. Note that a handler executed for an asynchronous subscription cannot access a map from a previous synchronous or asynchronous handler execution.
- Logging errors, warnings, and information to the same trace and error logs used by the server. Both synchronous and asynchronous handlers can log to the Handlers subsystem.
  HandlerCallContext provides methods for writing to a trace log at a specified level, provided logging is enabled with TraceLoggingConfiguration. If the trace level specified is not enabled in TraceLoggingConfiguration, the server suppresses messages for that trace level.
  
  HandlerCallContext also provides methods for logging specified error or warning messages. For these types of messages, you cannot specify the level of detail, so log them sparingly to avoid cluttering the trace and error logs.
- Checking what access rights a particular user has for a given object. The getAccessAllowedFor method returns an AccessRight bit mask for a specified object and user.
- Checking if the Content Platform Engine is in a shutdown state, allowing a handler to shut itself down gracefully and return control to the server.
Examples

To get a HandlerCallContext object:
HandlerCallContext hcc = HandlerCallContext.getInstance();

To set a property in the map:
hcc.getSharedMap().put("CascadeDelete", event.get_SourceObjectId());

To read from the map:
Id vsId = (Id)hcc.getSharedMap().get("CascadeDelete");

To log the Handlers subsystem:
if(hcc.isDetailTraceEnabled()) { hcc.traceDetail("My trace info..."); }

To check the access that user Alice has for a document:
ObjectReference docRef = doc.getObjectReference(); // "doc" is the object to check int access = hcc.getAccessAllowedFor(docRef, "Alice");
See Also:

Trace Logging Concepts

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract com.filenet.pch.Duration`	`createPCHDuration(com.filenet.pch.Accumulator accmt)` Creates and returns a PCH Duration object linked to a specified Accumulator.
`abstract int`	`getAccessAllowedFor(ObjectReference obref, java.lang.String user)` Return the access bits that a given user has to some object.
`abstract ContentConversionServices`	`getContentConversionServices()` Returns a utility interface for accessing content conversion services.
`abstract java.lang.String`	`getCurrentUserId()` Returns the identity of the user on whose behalf the handler has been called.
`static HandlerCallContext`	`getInstance()` Returns a `HandlerCallContext` object.
`abstract com.filenet.pch.Container`	`getPCHContainer(java.lang.String name)` Returns a PCH Container having a specified leaf name under which the calling handler can maintain statistics concerning its operation.
`abstract Property`	`getReadProtectedProperty(EngineObject src, java.lang.String propertyName)` Returns the `Property` object representing the normally inaccessible value of a read-protected property.
`java.util.Map`	`getSharedMap()` Returns a `Map` object with key/value pairs.
`abstract java.lang.String`	`getTemporaryFilesDirectory()` Returns the path to the directory into which the calling handler should place any temporary files it requires.
`abstract java.lang.Object`	`getTransactionKey()` Returns an opaque object representing the transaction context in which the handler is executing, if any.
`abstract boolean`	`isDetailTraceEnabled()` Indicates whether detailed-level tracing is enabled for the Handlers subsystem.
`abstract boolean`	`isModerateTraceEnabled()` Indicates whether moderate-level tracing is enabled for the Handlers subsystem.
`abstract boolean`	`isShuttingDown()` Indicates whether the server is in the process of shutting down.
`abstract boolean`	`isSummaryTraceEnabled()` Indicates whether summary-level tracing is enabled for the Handlers subsystem.
`abstract void`	`logError(java.lang.Object obj)` Writes the specified error to the server error log and trace log.
`abstract void`	`logWarning(java.lang.Object obj)` Writes the specified warning to the server trace log.
`abstract void`	`traceDetail(java.lang.Object obj)` Writes the detailed-level trace message to the server trace log.
`abstract void`	`traceModerate(java.lang.Object obj)` Writes the moderate-level trace message to the server trace log.
`abstract void`	`traceSummary(java.lang.Object obj)` Writes the summary-level trace message to the server trace log.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getInstance
```
public static final HandlerCallContext getInstance()
```
    Returns a HandlerCallContext object.
  - getSharedMap
```
public final java.util.Map getSharedMap()
```
    Returns a Map object with key/value pairs. The map is created by a handler for inter-handler communications in an operation chain.
  - logError
```
public abstract void logError(java.lang.Object obj)
```
    Writes the specified error to the server error log and trace log.
    
    Parameters:
    
    obj - The object specifying the error.
  - logWarning
```
public abstract void logWarning(java.lang.Object obj)
```
    Writes the specified warning to the server trace log.
    
    Parameters:
    
    obj - The object specifying the warning.
  - traceDetail
```
public abstract void traceDetail(java.lang.Object obj)
```
    Writes the detailed-level trace message to the server trace log.
    
    Parameters:
    
    obj - The object specifying the message.
  - traceModerate
```
public abstract void traceModerate(java.lang.Object obj)
```
    Writes the moderate-level trace message to the server trace log.
    
    Parameters:
    
    obj - The object specifying the message.
  - traceSummary
```
public abstract void traceSummary(java.lang.Object obj)
```
    Writes the summary-level trace message to the server trace log.
    
    Parameters:
    
    obj - The object specifying the message.
  - isDetailTraceEnabled
```
public abstract boolean isDetailTraceEnabled()
```
    Indicates whether detailed-level tracing is enabled for the Handlers subsystem.
  - isModerateTraceEnabled
```
public abstract boolean isModerateTraceEnabled()
```
    Indicates whether moderate-level tracing is enabled for the Handlers subsystem.
  - isSummaryTraceEnabled
```
public abstract boolean isSummaryTraceEnabled()
```
    Indicates whether summary-level tracing is enabled for the Handlers subsystem.
  - getAccessAllowedFor
```
public abstract int getAccessAllowedFor(ObjectReference obref,
                                        java.lang.String user)
```
    Return the access bits that a given user has to some object.
    
    Parameters:
    
    obref - the object to test. This must be a reference to an IndependentObject, such as a domain, object store, document, folder, custom object or class definition (to name just a few).
    
    user - the user for whom the rights are determined. This string can be a short name, DN, SID or, if on an Active Directory, a UPN. This cannot be a group name.
    
    Returns:
    
    the AccessRight bits that user has to obref. If the object doesn't exist or if the user has no access to the object, then zero is returned.
    
    Throws:
    
    EngineRuntimeException - E_OBJECT_NOT_FOUND if the user was not found in the configured LDAP setup.
  - getTransactionKey
```
public abstract java.lang.Object getTransactionKey()
```
    Returns an opaque object representing the transaction context in which the handler is executing, if any. This object overrides hashCode and equals to allow a handler to determine if different calls made to it are within the same transaction and to use the object as a key in a hash map.
    
    Returns:
    
    An opaque object representing the transaction context or null if no transaction is in progress.
  - getCurrentUserId
```
public abstract java.lang.String getCurrentUserId()
```
    Returns the identity of the user on whose behalf the handler has been called. This method is functionally equivalent to calling Factory.User.fetchCurrent followed by get_Id() on the returned User object but offers superior performance.
    
    Returns:
    
    The identity string for the current user.
  - isShuttingDown
```
public abstract boolean isShuttingDown()
```
    Indicates whether the server is in the process of shutting down.
    It is recommended that a handler call this method before making an API call to the server. If the method returns true, the handler should clean up and return control to the server.
    
    API calls to the server in a shutdown state will fail. As a result, a handler that is unaware of the server's shutdown state might write misleading error messages to the P8 log about the cause of the failures. The number of false error messages can be especially large for handlers processing batches of items in a loop. In such cases, a handler should call this method at the top of the processing loop.
    
    Returns:
    
    true if the server is shutting down.
  - getContentConversionServices
```
public abstract ContentConversionServices getContentConversionServices()
```
    Returns a utility interface for accessing content conversion services.
    
    Returns:
    
    An instance of ContentConversionServices
  - getReadProtectedProperty
```
public abstract Property getReadProtectedProperty(EngineObject src,
                                                  java.lang.String propertyName)
```
    Returns the Property object representing the normally inaccessible value of a read-protected property. A read-protected property is a binary-valued property whose IsReadProtected metadata property is set to true.
    Note: this method cannot be used in an asynchronous event handler to retrieve read-protected properties from the SourceObject of the event.
    
    By convention, a password or other sensitive string value is stored in a read-protected property as the bytes of the UTF-8 encoding of the string. This convention is applied by the Administration Console for Content Platform Engine to such properties that it manages. Applications can use read-protected properties for other purposes and with other encoding conventions.
    
    Read-protected custom properties are encrypted when stored in the object store database in the same way as encrypted system properties. The encryption and decryption is handled transparently by the Content Platform Engine server.
    
    Parameters:
    
    src - The EngineObject having the read-protected property.
    
    propertyName - The symbolic name of the read-protected property.
    
    Returns:
    
    The Property object containing the value.
    
    Throws:
    
    EngineRuntimeException - API_PROPERTY_NOT_IN_CACHE if the requested property is not in the property cache. For more information, see Property Cache Concepts in the Properties topic.
  - getTemporaryFilesDirectory
```
public abstract java.lang.String getTemporaryFilesDirectory()
```
    Returns the path to the directory into which the calling handler should place any temporary files it requires. The directory so referenced is guaranteed to exist.
    
    Returns:
    
    The directory path.
  - getPCHContainer
```
public abstract com.filenet.pch.Container getPCHContainer(java.lang.String name)
```
    Returns a PCH Container having a specified leaf name under which the calling handler can maintain statistics concerning its operation.
    
    Parameters:
    
    name - The leaf name for the container.
    
    Returns:
    
    The PCH Container instance
  - createPCHDuration
```
public abstract com.filenet.pch.Duration createPCHDuration(com.filenet.pch.Accumulator accmt)
```
    Creates and returns a PCH Duration object linked to a specified Accumulator.
    
    Parameters:
    
    accmt - The Accumulator to which the Duration should be linked
    
    Returns:
    
    The PCH Duration instance

Methods inherited from class java.lang.Object

getInstance

getSharedMap

logError

logWarning

traceDetail

traceModerate

traceSummary

isDetailTraceEnabled

isModerateTraceEnabled

isSummaryTraceEnabled

getAccessAllowedFor

getTransactionKey

getCurrentUserId

isShuttingDown

getContentConversionServices

getReadProtectedProperty

getTemporaryFilesDirectory

getPCHContainer

createPCHDuration