See: Description
Interface | Description |
---|---|
Event |
Represents an event that is published by a producer and received by a
consumer.
|
EventFilter |
The event filter criteria is applied against EventMetaData to determine if a
subscription matches a published event.
|
EventingService |
Object used to perform various Eventing Framework operations, such as
subscribing for events.
|
EventListener |
The EventListener allows a snap-in to be informed of events.
|
EventMetaData |
The data against which subscription filter criteria are applied.
|
EventProducer |
The object used by a producer to publish an event.
|
EventSubscription |
An event subscription.
|
EventSubscriptionAttributes |
Specifies the various attributes of a subscription.
|
SubscriptionSelectionFilter |
A filter used to select subscriptions.
|
TheEventListener |
TheEventListener allows a snap-in to be informed of events published through
the Eventing Framework.
|
Class | Description |
---|---|
EventingFactory |
Factory used to create Eventing Framework objects like EventSubscriptionAttrs and EventProducer.
|
EventingResultCode |
Values used to indicate the result of various operations available in the
Avaya Breeze Eventing API.
|
Exception | Description |
---|---|
EventingException |
A runtime exception used to indicate error conditions in the Avaya
Breeze Eventing API.
|
The Eventing Framework provides the ability for a snap-in to generate notifications about "interesting events" that can then be received by other snap-ins with an interest in these events. A snap-in that generates events operates in the role of an event producer while a snap-in that receives events operates in the role of an event consumer. A snap-in may operate as a producer at one point in its operation and operate as a consumer at another point. Conceptually the Eventing Framework operates in a fashion somewhat similar to Java Messaging Service (JMS) topics.
One important characteristic of the Eventing Framework is that the communication mechanism it provides results in a loose coupling of producers to consumers. This characteristic is achieved both by allowing producers to publish events without regard to which consumers may actually receive the event and by allowing consumers to indicate interest in receiving an event through subscriptions.
Another important characteristic of the Eventing Framework is its preferred version capabilities. Within Avaya Breeze, snap-ins of different versions can be installed and active, and one of the versions can be designated as the preferred version. A couple options available when subscribing for events allow a snap-in to indicate that it wants preferred version handling of the subscription. More information about the preferred version capabilities appears below.
Events are identified by their types, which are then organized into families. Events can be represented in a fully qualified form as family:type (for example, Call:CALL_OFFERED_FROM_CALLING_PARTY).
For example, notifications about the setup and termination of calls are a common type of event in Avaya Breeze. A snap-in wishing to receive call-related events would subscribe for any or all of the following event types in the Call family:
CALL_OFFERED_FROM_CALLING_PARTY - a new call has been
initiated by a calling party
OFFERING_CALL_TO_CALLED_PARTY - a new call is being
routed to a called party
CALL_ALERTING - the called party's phone is alerting
the party about the arrival of a new call
CALL_ANSWERED - the called party has answered the
call
CALL_ENDED - the call has ended
The producer for call events is a snap-in named "Call Event and Control", which is provided with Avaya Breeze. As calls are processed through the system, the Call Event and Control snap-in operates as a producer and publishes all of the events listed above. A snap-in that has subscribed for these events is then notified of these events through an event listener that it implements.
The Eventing Framework is not limited for use with pre-defined events. The framework is a general purpose API and provides substantial flexibility for passing events through it. A producer that makes use of the Eventing Framework simply needs to define an event by deciding what the event will contain. Required data for an event are an event family, an event type, and an event version number. The event family is a higher level identifier used to group like event types together. The version number allows a producer to define different versions of events, if desired. In addition to these required data elements, an event typically will include an event body (which is also referred to as the event "payload"). The payload is one or more pieces of data that carry information that would generally be of interest to a consumer. For example, the calling/called party and call ID are some of the pieces of data that are included with events from the Call family. The event body typically might contain a JSON representation of the data, but it might also be represented as XML. Or it might simply be a single-valued string. The format of the event body is determined by the producer; the Eventing Framework imposes no particular requirements on the structure, other than the data must be representable as a string.
Of course for a consumer to make use of an event -- and in particular, the event body -- the definition of the event must be known by the consumer. Interestingly, the Eventing Framework has no awareness of most of the definition of an event. And any awareness it does have is discerned at subscription or publication time. Therefore, the Eventing Framework generally provides no mechanism for storing event definitions. An exception is an event catalog that exists solely for use with Avaya Engagement Designer. The catalog contents are viewed and/or maintained through the Avaya Engagement Designer Administration Console. Note that no validation against the event catalog is done for events that pass through the framework.
Any event, whether in the catalog or not, can pass through the Eventing Framework as long as a producer and a consumer have a common definition of the event. All that has to happen for an event to be passed from a producer to a consumer is this. The consumer must subscribe for the event by specifying a family, an optional type, and possible additional filtering data (discussed below). A producer must then publish an event that matches the family, type, and additional filtering data. The published event is then "resolved" by matching it to the subscriptions of the consumer, and the event is delivered.
Sample code that illustrates these capabilities are available in the
com.avaya.collaboration.eventing.sample
portion of this Javadoc.
Ideally a consumer should receive all events for which it has interest and no events for which it does not have interest. This is the purpose of the filtering capabilities provided by the Eventing Framework. For producers, in addition to the event data already mentioned (family, event type, version, and event body), additional data elements called "metadata" can be provided as part of an event publication (the EventMetaData class is used to provide this data during publication). The intent of these metadata fields is to allow a consumer to provide a filter at subscription time as a way of excluding events for which the consumer has no interest. The following general purpose metadata can be provided by a producer:
user
correlation ID
The meaning of the data provided for these elements is determined by the
producer and they are all optional. The purpose of the user element is to
provide a value that represents a user associated with the event, if there is
a meaningful value for such a user. The correlation ID is intended to hold a
value that can be used to associate the event with some other prior
interaction between the producer and consumer. Additionally, arbitrary
key/value pairs of strings can also be provided using the setValue
method of the EventMetaData
class.
The EventMetaData class also allows the producer to specify the
producer name and version; at this time no filtering is possible against
these values.
A consumer can filter on these values through use of the EventFilter class, which has the following elements that correspond to the metadata values on the producer side:
user - used to filter against the metadata user
correlation ID - used to filter against the metadata
correlation ID
criterionMap - used to filter against the metadata
key/value pairs
criterionIgnoreCaseMap - used to filter against the
metadata key/value pairs using a case-insensitive match on the values
An additional element called "serviceProfile" can be specified in the EventFilter. A value specified here will be matched against the service profile configured in Avaya Aura System Manager for the user given in the metadata (if any such service profile has been configured for the user).
The option specified through the method setMatchConsumerToUserViaServiceProfile
of the EventSubscriptionAttributes
class
also includes an element of dynamic filtering based on user and service profile.
EventSubscriptionAttributes
class.
The purpose of these methods is to allow one snap-in to subscribe on behalf
of another. Typical use cases for this type of action might be when a group
of snap-ins are organized in a parent/child relationship or when one snap-in
acts as a broker for other snap-ins. In such cases it is useful for the
"parent" or "broker" snap-in to include information about the "dependent"
snap-in on whose behalf the subscription is being made. Setting the consumer
name and version has no effect on which snap-in receives the event; events
are always delivered to the subscribing snap-in. It simply acts as a form of
"documentation" so that an arriving event can be easily matched to the
dependent snap-in. It is interesting to note that these methods are used
internally by the Avaya Engagement Designer snap-in to subscribe for
events on behalf of workflow definitions.
Many areas of Avaya Breeze support a form of routing of requests and/or data to snap-ins that uses preferred version routing. Essentially, the functionality makes it possible, when multiple versions of a snap-in are installed, to indicate a preferred version in Avaya Aura System Manager as the one that should be considered the "active" one for most operations.
The Eventing Framework supports preferred version routing at two levels:EventSubscriptionAttributes
EventSubscriptionAttributes
The "deliver to preferred version" option behaves as follows. Assume there are two or more versions of a consumer snap-in installed on the system. Each of them has subscribed for the same event. When the deliver-to-preferred-version option has not been selected, a published event that matches these subscriptions will result in delivery of the event to each version of the snap-in. However, if they all have subscribed using this option, only a single event will be delivered and it will be delivered to the version marked as preferred. If no version is configured as preferred, then delivery is to the latest version.
The "populate consumer preferred version" works in conjunction with the methods setConsumerName and setConsumerVersion of theEventSubscriptionAttributes
class as
follows. Assume that a parent or broker snap-in (as described in an earlier
section above) creates two or more subscriptions that are identical except
for the consumer name and version settings. Further they specify the same
snap-in name but different versions of the snap-in. If the
populate-consumer-preferred-version option has not been selected, a published
event that matches these subscriptions will result in the delivery of
multiple events, one per version. However, if the
populate-consumer-preferred-version option has been selected, only a single
event will be delivered and the version number of the preferred version will
be the value provided in the event. If no version is configured as preferred,
then the value will be set to the latest version installed on the system.
The Eventing Framework replicates subscriptions throughout a cluster. This is useful for scenarios where activity on a single node -- perhaps an HTTP request arriving at a snap-in -- triggers the snap-in to subscribe for an event. The replication of the subscription throughout the cluster then ensures that a matching event published on any node will be delivered to the snap-in on that node, thereby creating a form of distributed processing of events.
It will probably be of no surprise to realize that there are a class of events where the same subscriptions are most conveniently created on all nodes. The most obvious example of this type of subscription is for those subscriptions that need to be created during the start up of a snap-in. The Eventing Framework makes this action convenient by automatically detecting and eliminating identical subscriptions, whether the subscriptions are made across nodes or within a node. Further, identical subscriptions have the same subscription ID both across nodes and within a node. A side-effect of detecting and eliminating identical subscriptions is to extend the expiration time of the original subscription as if the renew method, described in the section "Subscription Expiration" below, was called. Exactly what constitutes identical subscriptions is covered in the next section.
Creating identical subscriptions on different nodes, in practice, is generally straightforward. Snap-ins that use common code and data to create subscriptions will almost naturally create identical subscriptions that resolve to a single subscription across nodes. However, there is an area to be careful with in this respect. Subscriptions provide the ability for a snap-in to provide consumer private data as part of a subscription. The consumer private data is any serializable Java element that a snap-in finds useful to have returned to it when an event is delivered. As will become apparent in the next section, subscriptions that are created with different values for their consumer private data will exist as distinct subscriptions. While this mechanism provides a great deal of flexibility, it also presents a possible pitfall. If the consumer private data of a subscription happens to include any pieces of data that vary on different nodes, subscriptions that are intended to be identical across nodes will end up being different. For example, the inclusion of a node ID in consumer private data would cause this kind of difference to be present. So it is important to keep this possibility in mind when deciding what to include in consumer private data.
The processes of subscribing, unsubscribing, and refreshing subscriptions are not performed as atomic operations. Therefore, if a subscribe takes place on one node in a cluster for a subscription around the time that an unsubscribe is taking place on another node in the cluster for the identical subscription, there is no guaranteed order in which they will be processed. This behavior generally should not cause a problem, since nodes within a cluster are homogeneous and an installed snap-in will exhibit the same behavior in the same timeframe on all nodes in those cases where multiple nodes are subscribing/unsubscribing for identical subscriptions. However, network propagation delays and natural variations in the timing of when snap-ins perform the “same” operations could result in non-deterministic results if subscribes and unsubscribes are performed repeatedly in a short period of time.
Subscriptions are considered to be identical if there are no
differences in the values specified in the attributes of the
EventSubscriptionAttributes
class
used to create the subscriptions. This means, for example, if one
subscription is created for the Call family where no types are set in the
EventSubscriptionsAttributes and another subscription is created with the
same attributes except that a specific type is specified, the two
subscriptions are not identical and two subscriptions will be created in the
Eventing Framework. Similarly, if the correlation ID of a subscription filter
is left as null in one subscription and it is set to an explicit value in
another with all other attributes being the same, the subscriptions will
exist as different subscriptions.
A subtle implication of this definition for identical subscriptions is that subscription identity is not affected by time, even if multiple subscribes and unsubscribes take place over a long period of time. Most people probably would find this characteristic to be counter-intuitive. But this characteristic of subscriptions is an important part of the algorithm used to match and eliminate duplicates across nodes.
Another implication of this definition is the following. Generally, one published event will be delivered to a consumer as one event per subscription that matches the published event. Therefore, a consumer may have multiple events delivered for a single publication of an event. For example, in the case where a correlation ID has been left null in one subscription and explicitly specified in another with all other attributes being equal, a published event matching the explicit correlation ID will also match the "wild card" case (a null correlation ID in the filter) and the event will be delivered twice.
There are three important exceptions to this behavior. The first is the event notification reduction that occurs as a result of the preferred version functionality described above.
The second is event notification reduction that
occurs with the "match consumer to user via service profile" option (see the
setMatchConsumerToUserViaServiceProfile method
of the EventSubscriptionAttributes
class).
In this case the dynamic determination of consumer version will result in the
elimination of duplicate events, if the only differences between events is
in the version that gets determined dynamically.
The Avaya Breeze by default includes a special snap-in called the EventingConnector on certains types of clusters. Among other things, this snap-in provides an HTTP interface into the Eventing Framework for publishing events. The interface exposes the majority of attributes that can be specified when using the Eventing Framework Java API. The format of the URL is:
https://securityModuleIP/services/ EventingConnector/events
and it accepts the request as a post method using an encoding type of "multipart/form-data".
The following parameters are accepted and correspond to the "producer" portion of the Eventing Framework Java API as indicated:EventingFactory
EventingFactory
EventingFactory
EventingFactory
EventMetaData
EventMetaData
EventMetaData
EventMetaData
Additionally, arbitrary parameters can be specified as "metadata-keyname",
where "metadata-" is the literal "metadata-" and keyname is an arbitrary
string (characters typically known to be special characters are best
avoided). Parameters of this type are treated as key values pairs, where the
key is formed by stripping "metadata-" from the parameter name and the value
is the parameter value. These key/value pairs are then added to the
EventMetaData
object using the
addValue method.
com.avaya.collaboration.eventing.sample
portion of this Javadoc
As a means of clearing out orphaned subscriptions (subscriptions made by a
snap-in that is no longer installed), subscriptions expire after about 8 to 9
hours. Therefore, snap-ins will need to renew subscriptions periodically. To
make this process easy, a "SUBSCRIPTION_EXPIRING" event from the family
"Eventing" will be sent to consumers shortly before expiration. Then,
snap-ins are expected to renew the subscription by calling the "renew" method
of the EventingService class upon receipt of this event to keep the
subscription active. The
SampleEventListener
sample
includes code showing how this is done.
Please note that the expiration functionality of the EF is for the purpose of eliminating subscriptions that have become non-functional due a snap-in being unable to receive a matching event. This condition can arise, for example, if a snap-in becomes non-functional or it has been uninstalled. A snap-in should not rely on this functionality to clean out subscriptions that it no longer needs; instead, unneeded subscriptions should be removed through an explicit "unsubscribe" near the time they are no longer needed.
There is no guarantee when an expired subscription will be purged from the system or even if an expired subscription will be purged. Therefore, if a snap-in relies on the expiration mechanism to remove unneeded subscriptions, it is possible that unneeded subscriptions may unnecessarily exhaust the resources available for holding subscriptions.
Additionally, given the imprecise timing when subscriptions may be purged, if a subscription is allowed to expire and then an identical subscription is subsequently created (essentially a re-subscription), it is possible that the pending purge of the expired subscription might cause the re-subscription to be purged.
Therefore, when the SUBSCRIPTION_EXPIRING event is delivered to a snap-in, the subscription should be renewed to ensure the desired behavior of the EF. An explicit unsubscribe of the subscription upon receipt of this event is also acceptable. Any other use of this event may lead to unexpected results.
com.avaya.collaboration.eventing.families
for certain predefined
events.Copyright © 2023 Avaya. All rights reserved.