By setting properties and policies, event content can be automatically
completed.
Why and when to perform this task
In some situations, you might want some event property data to
be automatically set for every event you create. This is a way to fill in
certain standard values that do not change (such as the application name),
or to set some properties based on information available from the runtime
environment (such as creation time or thread information). You can also set
policies that govern event content according to business rules; for example,
you might require that any event with a particular extension name have its
severity set to a certain value.
You can do this by creating a content
handler. A content handler is an object that automatically sets the property
values of each event based on any arbitrary policies you want to use. The
Common Event Infrastructure does not restrict how a content handler can modify
event data, so long as the event still conforms to the Common Base Event specification.
To
ensure that all event sources comply with the same policies, you can create
an event factory associated with a content handler (using EventFactoryFactory)
and then bind the created event factory into a JNDI namespace. Instead of
creating their own event factories, event sources can then perform JNDI lookups
to access the event factory that already exists, without any knowledge of
the content handler. If your business rules later change, you can modify the
content handler in one place.
An event source does not need to do anything
to enable content completion. If an event factory is associated with a content
handler, each event it creates carries with it a reference to that content
handler. When the event is submitted to an emitter, the event calls the completeEvent()
method of the content handler, passing a reference to itself. This ensures
that the correct policies are applied to the event after the event source
is finished setting event-specific properties, but before the event is validated
and processed by the emitter.
Note: When an event is transmitted from one process
to another, the reference to the content handler is not transmitted with it.
This is because content completion relies upon the environment where the event
originates, and the necessary information might not be available elsewhere.
This restriction does not affect calls between applications that are local
to one another (for example, a call to an enterprise bean using its local
interface).
To create a content handler, follow these steps:
Steps for this task
- Create a new Java class implementing the org.eclipse.hyades.logging.events.cbe.ContentHandler
interface. This interface defines a single method called completeEvent(CommonBaseEvent);
the parameter is the event whose content is to be completed. In your implementation
of this method, you can use the getter and setter methods of CommonBaseEvent
to process the event property data in accordance with any policies that apply.
Note: When
an event source uses JNDI to retrieve an event factory, the content handler
is returned along with the event factory. For this reason, the content handler
must be serializable.
The following example is a
simple content handler that automatically sets the extension name of each
event:
import java.io.Serializable;
import org.eclipse.hyades.logging.events.cbe.*;
public class BusinessContentHandler
implements ContentHandler, Serializable {
public void completeEvent(CommonBaseEvent event)
throws CompletionException {
event.setExtensionName("business");
}
}
- Associate the content handler with an event factory. To
do this, specify the content handler when creating the event factory:
EventFactory eventFactory =
(EventFactory) EventFactoryFactory.createEventFactory(contentHandler);
The returned event factory is permanently associated with the
specified content handler.