IBM FileNet P8, Version 5.2

Action Handlers: Restrictions and Best Practices

You can extend Content Engine functionality by implementing one or more Java™ interfaces in the com.filenet.api.engine package. As a guide for making implementation choices, this topic provides restrictions, best practices, and feature comparisons.

For some server extensibility use cases, knowing whether to use a change preprocessor or an event action handler is not always obvious, especially if you want to modify the source object. The following table compares features of change preprocessors, which aways execute synchronously, with features of event action handlers, which you can configure to run either synchronously or asynchronously.

	Change Preprocessor - synchronous	Event Action - synchronous	Event Action - asynchronous
When does action handler run? (Any request to the Content Engine can trigger one or more of each server extension type.)	In transaction, before database updates have occurred. Runs first.	In transaction, after database updates have occurred. Runs second.	After transaction has committed. Runs third in a separate transaction.
Executes before source object is saved?	yes	yes	no
Server disables security access checks during execution?	no	yes	yes
Gap in time between client saving source object and handler executing?	no	no	yes
Can update source object?	yes	no	yes
Can update SettableOnlyonCreate (SOOC) properties?	yes	no	no
Can update other objects referenced by OVPs (object-valued properties)?	yes	yes	yes
Can subscribe to events?	no	yes	yes
Execution can be filtered by event and property values?	no ¹	yes	yes
Unhandled exceptions rollback the user's transaction?	yes	yes	no

¹ Change preprocessors are invoked unconditionally. However, the source object passed to a change preprocessor action handler includes a properties collection and a set of pending actions, allowing the action handler to filter by event and property values.

Exception Handling

The server makes extensive use of JEE transactions to ensure that persisted data is correct and consistent. To avoid undermining the transactional consistency of the server, handler code must always throw some exception in response to an exception thrown by the Content Engine API. Throwing the exception ensures that the server rolls back the surrounding transaction and cleans up any inconsistent database activities. It is not safe to catch a Content Engine API exception and treat it as a soft or recoverable failure.
You must wrap any thrown checked exception with a subclass of RuntimeException. The server catches a thrown exception and wraps it with an EngineRuntimeException.

Restrictions

You cannot update the source object passed to a synchronous event action handler or a lifecycle action handler. It is not supported. Updating the source object in a synchronous event action handler results in persistence issues.
To update a source object, use a change preprocessor or asynchronous event action handler, as described in "Best Practices" below.
In synchronous action handlers, you cannot recursively fire more than fifty events without encountering an EVENT_INFINITE_LOOP_DETECTED exception.
In both synchronous and asynchronous action handlers, you cannot create metadata and then use it for instance creation. For example, creating an instance of a newly created document subclass, as shown in the following code snippet, will fail with a BAD_CLASSID exception.
```
 ClassDefinition myNewDocSubclass =createDocSubclass(); 
Document doc = Factory.Document.createInstance(objectStore,
   myNewDocSubclass.get_SymbolicName()); 
doc.save(RefreshMode.REFRESH); 
```
Do not use action handler code to display GUI elements. If you attempt to do so, the results are unpredictable and could cause problems a serious as hanging the Content Engine.
GetContentEvent is a subscribable event of type RetrievalEvent, which does not have a source object property. Therefore, an event action handler that receives a GetContentEvent cannot retrieve the source object from the passed-in event. It must retrieve the persisted source object from the object store, using the event's SourceObjectID property.

Best Practices

All action handlers run within a JEE transaction. Transactions always have a time limit, and it's a good practice to have a transaction open for as short a time as you can. Synchronous action handlers and change preprocessor handlers share transaction time with all other activity in an RPC (remote procedure call), such as other updates and action handlers, and an exception rolls back the entire transaction. Asynchronous handlers each gets its own transaction.
The overall overhead of asynchronous is higher than the overhead of synchronous (because of queuing for later execution). Therefore, you should use synchronous when you can, and use asynchronous where synchronous execution is not appropriate.

In either execution mode, activity in a handler should be as brief as it can be. For long-running activity (for example, a callout to another system), consider adding information to some external queuing mechanism so that your own handler code can complete quickly.
You can update a source object with an asynchronous event action handler or a change preprocessor, which runs synchronously. Because a change preprocessor executes before the source object is persisted (unlike an asynchronous event action handler), it should be used to alter settable-only-on-create or settable-only-on-checkin (SOOC) properties, or to validate properties by modifying values or rolling back the entire transaction if need be.
A change preprocessor should also be used in cases when the handler must complete in time to satisfy dependencies of other applications, such as a subsequent action of a client application that relies on the successful completion of the handler. With asynchronous event handlers, there is a brief window of time (usually seconds or minutes) between persistance of the target object in one transaction and any changes applied by the asynchronous event handler in a separate transaction. Therefore, avoid an asynchronous event handler if a dependent client cannot tolerate a time period when required handler changes have not been applied.

The advantage of an asynchronous event handler is that it does not have to share JEE transaction time with the triggering action. For updating a source object, consider using an asynchronous event action handler in these situations:
- The change preprocessor use cases described above do not apply.
- You require that the handler is invoked only by the firing of specific events on the source object (rather than any create, update, or delete server request invoked on a class instance).
To update a source object in an asynchronous event action handler, you must first fetch the persisted instance of the source object before updating it. You can call the save method on the fetched source object.
Do not update the source object passed to an asynchronous handler because the source object might already have changed before the handler executes, and, therefore, the object might be obsolete.
In event action handlers, lifecycle action handlers, and document classifiers, the source object of the action passed to the handler is a shallow copy of the object, which contains only the object's scalar (non-object) properties in the object's property cache. If you attempt to retrieve a property value that is not contained in the shallow copy, you will get an API_PROPERTY_NOT_IN_CACHE error message. To avoid the possibility of getting this error, you should check for the existence of a value in the property cache prior to accessing the property. If the value does not exist in the property cache, you should fetch the persisted object. For example:
```
IndependentObject sourceObj = event.get_SourceObject();
if (!sourceObj.getProperties().isPropertyPresent(PropertyNames.FOLDERS_FILED_IN)) 
{ 
   Id id = event.get_SourceObjectId(); 
   ObjectStore os = event.getObjectStore(); 
   // Fetch the source object. By specifying null instead of a property filter, 
   // all properties are retrieved.
   sourceObj = Factory.Document.fetchInstance(os, id, null); 
}
Property prop = sourceObj.getProperties().find(PropertyNames.FOLDERS_FILED_IN); 
FolderSet folders = (FolderSet) prop.getIndependentObjectSetValue(); 
 
```
As with other action handlers, a change preprocessor should also check for the existence of a value in the property cache. A change preprocessor runs regardless of the type of request type to the server (create, update, delete). For creation requests, the property cache is sparse, containing only client-provided and default values.