A subscription is a device for launching a user-implemented, server-side component that extends the core functionality of the Content Engine. A subscription is defined by one or more events, a target Content Engine object on which the events can be triggered, and an event action. When an event is triggered on the target object, the event action is executed. For example, you can have a subscription that notifies you by email (event action) when documents of the "Code Module" class (target object) are created (triggered event).
This topic focuses on setting up a subscription; that is, creating a subscription and setting its properties. For subscription code examples, see Working with Subscriptions. For information on subscriptions as implemented in the Enterprise Manager, see Event Actions and Subscriptions.
A subscription is represented by a
Subscription class,
which is the base class for InstanceSubscription
and ClassSubscription
(for general subscriptions),
and InstanceWorkflowSubscription
and ClassWorkflowSubscription
(for Workflow-related subscriptions).
A workflow-related subscription initiates a workflow and event action in response to events
triggered on a particular object, or on any object of a particular class.
To start, you use a Factory
method to create an instance of a subclass derived from Subscription
.
(You cannot create a base Subscription
object, but only retrieve one.)
After creating a subscription object, you define the following key properties:
CreationEvent
.
See Subscribed Events.In addition to the required properties above, there are subscription properties that specify:
See Subscription Properties for more information.
When you create a subscription, you set its SubscribedEvents property
to a collection of one or more system and custom events. If any of these events
is triggered on the subscription's target object, the Content Engine executes
the subscription's event action.
For example, if you subscribe to a FileEvent
object, filing a containable object
in a folder or creating a subfolder executes an event action.
The system events that you can subscribe to derive from the
ObjectChangeEvent interface.
If you need an event that's not already represented by a Content Engine system event,
then you can create a custom event. Custom events apply to subclasses of the
Subscribable
class, and are triggered by calling the class's RaiseEvent
method.
For example, you could create a custom event class, then set the instantiated custom event object to
the SubscribedEvents property of a subscription. To trigger the custom event,
you would raise the event on the Subscribable
object that is the
target object of the subscription. This, in turn, would fire the event action
in the subscription.
Note that the system and custom events that you can subscribe to can also be audited. See Auditing Concepts.
Event actions are code procedures that you implement to extend Content Engine functionality, and which are executed via subscriptions. Event actions can also be launched when you publish or republish a document. There are various use cases for event actions, such as the following:
You implement an event action as a Java class, based on the Content Engine API's EventActionHandler interface. After compiling and debugging your event handler, you can package the class in a JAR file. You can then check in your class or JAR file as a CodeModule object in a Content Engine object store, or, alternatively, you can specify the Java event handler in the classpath of the application server where the Content Engine is running. A handler will execute on the application server hosting the Content Engine.
You make an implemented event action handler available to a subscription or to a publish/republish operation through an
EventAction object. You can create and retrieve EventAction objects, as well as set and retrieve properties and permissions for them.
To associate an event action handler with an EventAction
object, you set the EventAction
's ProgId property to the fully qualified name of the Java class.
If you checked in the event handler to an object store, you must also set the
EventAction
's CodeModule property. You then set the subscription object's EventAction property
to the EventAction object. For a publish/republish operation, you specify the event action name or ID.
For best practices for implementing an EventActionHandler
interface, see Implementation Concepts. For code examples on implementing an event action handler and on creating an event action object, see Working with Subscriptions.
Note that you can use both a subscription and a publish/republish operation to launch two event actions on an object. That is, for a given publishable object, you can subscribe to PublishRequestEvent or PublishCompleteEvent to launch one event action, and you can use the publish or republish method on the object to fire a second event action. In this scenario, the event action set in the subscription mechanism will launch first, and the event action specified in the publish or republish method will launch second (if no exception is thrown from the first event action).