About the EventBroker

This topic includes the following sections:

•	What Is an Event?

•	Differences Between Application-defined and System-defined Events

•	What Is the EventBroker?

•	How the EventBroker Works

•	What Are the Benefits of Brokered Events?

What Is an Event?

An event is a state change or other occurrence in a running application (such as a network connection being dropped) that may require intervention by an operator, an administrator, or the software. The Oracle Tuxedo system reports two types of events:

•	System-defined events—which are situations (primarily failures) defined by the Oracle Tuxedo system, such as the exceeding of certain system capacity limits, server terminations, security violations, and network failures.

•	Application-defined events—which are situations defined by a customer application, such as the ones listed in Table 5‑1.

 

Table 5‑1 Application-defined Events

In an application for this type of business . . .	An occurrence of this situation may be defined as an “event” . . .
Stock brokerage	A stock is traded at or above a specified price.
Banking	A withdrawal or deposit above a specified amount is made.
	The cash available in an ATM machine drops below a specified amount.
Manufacturing	An item is out of stock.

Application events are occurrences of application-defined events, and system events are occurrences of system-defined events. Both application and system events are received and distributed by the Oracle Tuxedo EventBroker component.

Differences Between Application-defined and System-defined Events

Application-defined events are defined by application designers and are therefore application specific. Any of the events defined for an application may be tracked by the client and server processes running in the application.

System-defined events are defined by the Oracle Tuxedo system code and are generally associated with objects defined in TM_MIB(5). A complete list of system-defined events is published on the EVENTS(5) reference page. Any of these events may be tracked by users of the Oracle Tuxedo system.

The Oracle Tuxedo EventBroker posts both application-defined and system-defined events, and an application can subscribe to events of both types. The two types of events can be distinguished by their names: the names of system-defined events begin with a dot ( . ); the names of application-specific events cannot begin with a dot ( . ).

What Is the EventBroker?

The Oracle Tuxedo EventBroker is a tool that provides asynchronous routing of application events among the processes running in a Oracle Tuxedo application. It also distributes system events to whichever application processes want to receive them.

The EventBroker performs the following tasks:

•	Monitors events and notifies subscribers when events are posted via tppost(3c).

•	Keeps an administrator informed of changes in an application.

•	Provides a system-wide summary of events.

•	Provides a tool through which an event can trigger a variety of notification activities.

•	Provides a filtering capability, providing additional conditions to the posted event’s buffer.

Note:

For a sample application that you can copy and run as a demo, see “Tutorial for bankapp, a Full C Application” in Tutorials for Developing Oracle Tuxedo ATMI Applications.

The EventBroker recognizes over 100 meaningful state transitions to a MIB object as system events. A posting for a system event includes the current MIB representation of the object on which the event occurred and some event-specific fields that identify the event that occurred. For example, if a machine is partitioned, an event is posted with the following:

•	The name of the affected machine, as specified in the T_MACHINE class, with all the attributes of that machine

•	Some event attributes that identify the event as machine partitioned

You can use the EventBroker simply by subscribing to system events. Then, instead of having to query for MIB records, you can be informed automatically when events occur in the MIB by receiving FML data buffers representing MIB objects.

How the EventBroker Works

The Oracle Tuxedo EventBroker is a tool through which an arbitrary number of suppliers of event notifications can post messages for an arbitrary number of subscribers. The suppliers of such notifications may be application or system processes operating as clients or servers. The subscribers of such notifications may be administrators or application processes operating as clients or servers.

Client and server processes using the EventBroker communicate with one another based on a set of subscriptions. Each process sends one or more subscription requests to the EventBroker, identifying the event types that the process wants to receive. The EventBroker, in turn, acts like a newspaper delivery person who delivers newspapers only to customers who have paid for a subscription. For these reasons, the paradigm on which the EventBroker is based is described as publish-and-subscribe communication.

Event suppliers (either clients or servers) notify the EventBroker of events as they occur. We refer to this type of notification as posting an event. Once an event supplier posts an event, the EventBroker matches the posted event with the subscribers that have subscribed for that event type. Subscribers may be administrators or application processes. When the EventBroker finds a match, it takes the action specified for each subscription; subscribers are notified and any other actions specified by subscribers are initiated.

Figure 5‑1 shows how the EventBroker handles event subscriptions and postings.

Figure 5‑1 Posting and Subscribing to an Event

As the administrator for your Oracle Tuxedo application, you can enter subscription requests on behalf of client and server processes through calls to the T_EVENT_COMMAND class of the EVENT_MIB(5). You can also invoke the tpsubscribe(3c) function to subscribe, programmatically, to an event by using the EventBroker.

Event Notification Methods

The EventBroker subscription specifies one of the notification methods shown in Figure 5‑2.

Figure 5‑2 Supported Notification Methods

•	Notify a client—the EventBroker keeps track of a client’s interest in particular events and notifies the client, without being prompted, when such an event occurs. For this reason, this method is called unsolicited notification.

•	Invoke a service—if a subscriber wants event notifications to be passed to service calls, the subscriber process should invoke the tpsubscribe() function to provide the name of the service to be called.

•

Enqueue message to stable-storage queues—for subscriptions with requests to send event notifications to stable-storage queues, the EventBroker will obtain a queue space, queue name, and correlation identifier. A subscriber specifies a queue name when subscribing to an event. The correlation identifier can be used to differentiate among multiple subscriptions for the same event expression and filter rule, that are destined for the same queue.

•	Execute a command—when an event is posted, the buffer associated with it is transformed into a system command that is then executed. For example, the buffer may be changed to a system command that sends an e-mail message. This process must be executed through the MIB.

•	Write messages to the user log—when events are detected and matched by the EventBroker, the specified messages are written to the user log, or ULOG. This process must be executed through the MIB.

Severity Levels of System Events

The EventBroker assigns one of three levels of severity to system events such as server terminations or network failure.

Table 5‑2 shows the severity levels of system events.

 

Table 5‑2 Severity Levels of System Events

The level of severity is . . .	When the EventBroker is informed of . . .
ERROR	An abnormal occurrence, such as a server being terminated or a network connection being dropped.
INFO (short for “Information”)	A state change resulting from a process or a change in the configuration.
WARN (short for “Warning”)	The fact that a client has not been allowed to join the application because it failed authentication. A configuration change that threatens the performance of the application has occurred.

What Are the Benefits of Brokered Events?

•

Anonymous communication—the Event Broker enables Oracle Tuxedo programs to subscribe to events in which they are interested and it keeps track of all subscriptions. Therefore, a subscriber to one event does not need to know which programs subscribe to the same event, and a poster of an event does not need to know which other programs subscribe to that event. This anonymity allows subscribers to come and go without synchronizing with posters.

•	Decoupling of exception conditions—a publish-and-subscribe communication model allows the software detecting an exception condition to be decoupled from the software handling the exception condition.

•	Tight integration with the Oracle Tuxedo system—the EventBroker retains functionality such as message buffers, messaging paradigms, distributed transactions, and ACL permission checks for event postings.

•

Variety of notification methods—when a client or server subscribes to a system event (such as the termination of a server) or an application event (such as an ATM machine running out of money), it specifies an action that the EventBroker should take when it is notified that the target event has occurred.

If the subscriber is an Oracle Tuxedo client, it can do one of the following at the time it subscribes:

•	Request unsolicited notification

•	Name a service routine that should be invoked

•	Name an application queue in which the EventBroker should store the data for later processing

If the subscriber is an Oracle Tuxedo server, it can do one of the following at the time it subscribes:

•	Specify a service request

•	Name an application queue in which the EventBroker should store the data

See Also

•	Subscribing to Events on page 6‑1

•	Subscribing, Posting, and Unsubscribing to Events with the ATMI and the EVENT_MIB on page 6‑3 in Introducing Oracle Tuxedo ATMI

•	EVENT_MIB(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference

•	tpsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference

•	tpunsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference