Configuring Event Handlers Overview
Event handlers define how the SRC VTA processes events. An event handler configuration includes the following options:
Events—Type of event including tracking, update, or callback event; for example, a service-start tracking event.
Priority—Priority at which event handlers are evaluated and executed. Event handlers are evaluated and executed from low to high.
Condition—Condition that the event handler evaluates to determine whether the event handler should process the event.
Actions—List of actions to be performed by the event handler.
You can set up multiple event handlers to process events. For example, the first event handler could retrieve the balance for a quota account, and the next event handler could refill the quota account depending on whether the condition of the second event handler is met.
When an event is received, the corresponding event type and condition configured for the event handler are evaluated based on the priority. When a condition is met, the corresponding actions are performed according to the event attributes. The action can update or add event attributes to the events for subsequent processing of the same event. An action can invoke a function provided by any processor. After an event handler has completed its processing, event processing continues with the next applicable event handler.
The SRC VTA communicates with the SAE through the Enterprise JavaBean (EJB) adapter plug-in. When an event is sent by the ejb-adapter plug-in on the SAE, it is received by the SAEEventListener, which places the event in the event queue. Because you can have multiple VTA instances, each SRC VTA has a separate SAEEventListener. The SRC VTA takes events one by one and presents them to an ordered sequence of event handlers. Each event handler includes a list of actions. If the event handler is configured to handle the event, it acts on the event based on the configured actions—for example, updating a balance or starting a service. Each action can specify a function.
The ejb-adapter plug-in can use either the round-robin algorithm or the primary/backup algorithm to send events from the SAE to the SRC VTAs. When you configure the ejb-adapter plug-in, you specify a comma-separated list of SRC VTA IP addresses or hostnames. When you use the round-robin algorithm, an outgoing event from the SAE is sent to each of the SRC VTAs specified in the comma-separated list until it is handled by one of the SRC VTAs. When you use the primary/backup algorithm, the first SRC VTA in the comma-separated list is the primary SRC VTA; all others are secondary SRC VTAs. All outgoing events from the SAE are forwarded to the primary SRC VTA until it becomes full or inaccessible. When the handling of an event fails in the primary SRC VTA, the event is sent to the secondary VTAs in a round-robin fashion until one of the secondary SRC VTAs handles the event. On successful handling of the event, the secondary SRC VTA is promoted and becomes the new primary SRC VTA.
When you configure an event handler, you need to specify the priority for evaluating and running the event handler. The priority is an integer where the smaller number has the higher priority. The event handler with the highest priority receives the event, determines whether the event’s type is the same as the event type of the event handler, and determines whether the event satisfies the condition of the event handler. When an event handler finishes processing an event, the next applicable event handler according to the priority of the event handler processes the event.
Each SRC VTA event corresponds to one subscriber and contains some attributes. The SRC VTA supports the following event types:
Service and subscriber tracking events from the SAE; for example, start or stop tracking events.
Account update events triggered by updating database accounts.
Callback events triggered by an SRC VTA API call.
Various events can be received by the SRC VTA from the SAE. Table 1 describes the events supported by the SRC VTA.
Table 1: SRC VTA Event Types
Database update event
External callback event for the specified call
Service interim–tracking event for the specified service
Service start–tracking event for the specified service
Service stop–tracking event for the specified service
User interim–tracking event
User start–tracking event
User stop–tracking event
The service-name is the name of any configured SRC service.
To process an event, the event handler must be configured to handle the particular event type. You configure which events are handled by the event handler with the shared vta group name event-handler event-handler-name events events statement. Separate events with a comma. You can configure an event handler to handle multiple event types. If an event handler is configured to handle an event, it can pass that event to a sequence of actions.
An example of an event is:
The SRC software supports wildcard characters to configure an event for the specified service in event handler.
Each event carries attributes. Table 2 describes the types of attributes that are available for each type of event.
Table 2: Event Attributes
Service and subscriber tracking events from the SAE
Account update events
Use glob pattern matching when you configure an event for the specified service in event handler. The pattern matching happens only when SRC VTA receives a new service event from the SAE. After the pattern matching, the service name related event handlers are evaluated and executed based on the priority.
Use the following wildcard characters when you configure an event for the specified service in event-handler:
*—Matches any substring.
?—Matches any single character.
[range]—Matches a single character in the specified range. Ranges can have the form a-z, abcd, 0-9 or A-Z.
[!range]—Matches a single character outside the specified character or range of characters.
An example of an event for the specified service with a wildcard pattern:
Matches any service event that starts with Int8192-Usage_ and ends with a value other than 1, 2, or 3. In this case, the ‘does not match’ condition is checked because in this case the pattern begins with “!”.
Table 3 lists some examples of events with wildcard pattern and conditions.
Table 3: Wildcard Pattern and Conditions
Does not Match Condition
Guidelines for Using Glob Pattern in an Event Handler
Keep in mind the following considerations when using a wildcard pattern to configure service name related event in event-handler:
Glob matches are case sensitive.
A minor change in wildcard pattern may match unexpected events.
Must be aware of wildcard pattern and choose a wise configuration.
Follow these guidelines when using wildcard pattern:
Enclose patterns in double quotes.
For example:root@c5bng-src10# set RecordUsage events "service-start:Quota[2-3]"
Verify the VTA information logs after you configure a wildcard pattern in the VTA event handler and confirm that the event handlers are loaded as expected.
It is advised to use the same wildcard pattern throughout the event configuration, when you use a wildcard character for a service name in event-handler.
In GetQuota eventhandler configuration, if you use “service-start:Video-*” wildcard pattern for matching all the corresponding events and you want to match the same set of services in NoQuota eventhandler configuration, you must use the same “service-start:Video-*” wildcard pattern.
When you use the event name with a wildcard pattern which is also the service name, both the service name and the wildcard pattern matching the service name are considered for processing.
For the “service-interim:Sample[1-6]Test” event, the wildcard matches service names such as Sample[1-6]Test (which is a part of the event), Sample1Test, Sample2Test, Sample3Test, Sample4Test, Sample5Test, and Sample6Test.
When you specify the priority for evaluating and running an event handler, you must set different priorities for different event handlers. The event gets dropped when it has more than one event handler with same priority.
True—Event handler should handle the event.
False—Event handler should not handle the event.
If the condition is met, the SRC VTA performs the corresponding actions based on the event attributes. An action invokes a function and provides the parameters required by that function to the db-engine processor. If no condition is specified, true is returned as the value. If a referenced attribute does not exist in the event, the referenced attribute’s value is null. Following is an example condition:
When you configure an event handler, you specify actions that the event handler executes in response to an event; for example, updating an account balance, starting a service, or stopping a service. An action is performed only if the event matches the specified event type and condition you configure for the event handler. An action can invoke functions provided by any processor.
We recommend that when you configure event handlers and their actions, you ensure that for any given event, all database operations are performed before any other operations that have permanent effects. This is because if a database error occurs—for example, due to normal contention for database records between different event threads—the SRC VTA rolls back the current database transaction (no changes are made to the database) and then restarts processing the event. If the event performs some other operation other than database operations before such an error, such as start a service, then that other operation is performed again when the event is reprocessed following the error.