An API event occurs when an API method manipulates a human task.
Use the API event handler plug-in service provider interface (SPI) to create
plug-ins to handle the task events sent by the API or the internal events
that have equivalent API events.
Why and when to perform this task
Complete the following steps to create an API event handler.
Steps for this task
- Write a class that implements the APIEventHandlerPlugin2 interface
or extends the APIEventHandler implementation class. This class
can invoke the methods of other classes.
- If you use the APIEventHandlerPlugin2 interface, you must implement all
of the methods of the APIEventHandlerPlugin2 interface and the APIEventHandlerPlugin
interface.
- If you extend the SPI implementation class, overwrite the methods that
you need.
This class runs in the context of a Java 2 Enterprise Edition (J2EE)
Enterprise JavaBeans (EJB) application. Ensure that this class and its helper
classes follow the EJB specification.
Tip: If you want
to call the HumanTaskManagerService interface from this class, do not call
a method that updates the task that produced the event. This action results
in a database deadlock.
- Assemble the plug-in class and its helper classes into a JAR file.
If the helper classes are used by several J2EE applications, you
can package these classes in a separate JAR file that you register as a shared
library.
- Create a service provider configuration file for the plug-in in
the META-INF/services/ directory of your JAR file.
The configuration file provides the mechanism for identifying and
loading the plug-in. This file conforms to the Java 2 service provider interface
specification.
- Create a file with the name com.ibm.task.spi.plug-in_nameAPIEventHandlerPlugin,
where plug-in_name is the name of the plug-in.
For example,
if your plug-in is called Customer and it implements the com.ibm.task.spi.APIEventHandlerPlugin interface,
the name of the configuration file is com.ibm.task.spi.CustomerAPIEventHandlerPlugin.
- In the first line of the file that is neither a comment line
nor a blank line, specify the fully qualified name of the plug-in class that
you created in step 1.
For example, if your plug-in class is
called MyAPIEventHandler and it is in the com.customer.plugins package,
then the first line of the configuration file must contain the following entry: com.customer.plugins.MyAPIEventHandler.
Result
You have an installable JAR file that contains a plug-in that handles
API events and a service provider configuration file that can be used to load
the plug-in.
Tip: You only have one eventHandlerName property
available to register both API event handlers and notification event handlers.
If you want to use both an API event handler and a notification event handler,
the plug-in implementations must have the same name, for example,
Customer as
the event handler name for the SPI implementation.
You can implement both
plug-ins using a single class, or two separate classes. In both cases, you
need to create two files in the META-INF/services/ directory
of your JAR file, for example, com.ibm.task.spi.CustomerNotificationEventHandlerPlugin and com.ibm.task.spi.CustomerAPIEventHandlerPlugin.
Package the plug-in implementation and the helper classes in a single
JAR file.
What to do next
You now need to install and register the plug-in so that it is available
to the human task container at runtime. You can register API event handlers
with a task instance, a task template, or an application component.