Overview of WebLogic Events

 

WebLogic Event API provides a lightweight event management system using a publish/subscribe paradigm. For example, a WebLogic/JDBC client can submit (publish) events to a WebLogic Server. Other clients of the WebLogic Server can register interest in (subscribe) to those events. The WebLogic Server informs subscribers of new events when they occur.

A client can specify conditions, called an evaluator, that must be satisfied for an event to be delivered to them. Evaluators can prevent unnecessary network traffic. Evaluators are executed on the WebLogic Server.

The client also specifies what happens when the event occurs. The Action resulting from an event can be implemented either on the server or the client side. See Registering interest in an event later in this document.

As a service, WebLogic Events has access to all of WebLogic's other services, like JDBC, RMI, logging, instrumentation, Workspaces, etc. All of these services are integrated in WebLogic. Their APIs share many common aspects that make building a complex networked application easier; your application can use several services, all of which can share access to objects and client resources.

Several WebLogic Servers can operate together as a WebLogic Cluster to manage notifications and registrations, since any WebLogic Server can publish and subscribe to events on other servers simultaneously.

WebLogic Server implements JavaSoft's Java Messaging Service (JMS) specification. You can use WebLogic JMS in any application where you can use WebLogic Events. WebLogic JMS offers features not found in WebLogic Events, such as message persistence, point-to-point messaging, and guaranteed message delivery sequence. Since WebLogic JMS is an industry-standard interface, we recommend that you implement new event-based applications using WebLogic JMS. You may still choose to use WebLogic Events in applications that do not require the more sophisticated features JMS offers. The WebLogic Events service is small and fast, but limited compared to JMS. Read more about WebLogic JMS in Using WebLogic JMS.

 

---

WebLogic Event architecture

The Topic Tree

The Topic Tree is the chief architectural feature of WebLogic Events. The Topic Tree lives on the WebLogic Server and is populated by all of the Event Topics that clients have subscribed to. It is the data structure used to remember and process WebLogic Events as they are subscribed to and published by WebLogic Clients.

Structure of the Topic Tree

The tree structure allows event types to be grouped into categories and further sub-categories, where each branch in the tree represents a sub-category of the event it branches from. In a well organized Topic Tree, as we move from the root towards the leaf nodes, the Event Topics become more specific.

The notation used to describe events in the tree is similar to the dot-notation of domain addresses. Each word represents an event at a particular branch in the tree. For example comms.devices.telephone.ring or comms.devices.telephone.page. This allows clients to subscribe to a specific Event Topic, using the full event qualifier. This model also allows a client to subscribe to a general category of Event Topics, by only specifying interest to a branch level. E.g. comms.devices.telephone would listen for any events pertaining to a telephone.

However, the organization of the tree is the responsibility of the client applications that make up the WebLogic framework. It is your responsibility to program your system so that it organizes the events sensibly, to make the most of this structure.

An example of a structured tree

At the top (or root) of every Topic Tree is a wildcard topic that essentially denotes "every kind of event," which is notated with an asterisk (*). All other topics are considered to be more specific than the root topic. An application that registers interest in the root topic is able evaluate every event that occurs on the WebLogic Server, in the Topic Tree.

Figure 1-1 WebLogic's Topic Tree

 

In the example shown above, there are two major branches of topics that descend from the root, stocks and weather. We build a typical Topic Tree here for registrations of interest in weather in two California cities, Los Angeles and San Francisco. These topics would be notated as:

weather.northamerica.us.california.la

and

weather.northamerica.us.california.sf

Registering interest in an event

How the Topic Tree is populated

The Topic Tree is dynamically built inside the WebLogic Server as clients subscribe to Event Topics. If a client subscribes to an Event Topic that does not exist in the Topic Tree, a new node, and the new branches required to reach that node, are created automatically. The subscribing client will now receive notice of the new Event whenever it is published.

How a client registers interest in an Event Topic

A WebLogic Client must register interest in a topic with the WebLogic Server in order to evaluate, and act upon events when they are published. Any WebLogic Client application on the network can register interest in any number of Event Topics via the WebLogic EventRegistration services.

A registration is submitted to the WebLogic Server usually with the following pieces of information:

Which event to subscribe to, described by Registration Parameters

• How to Evaluate the event when it occurs, specified via an EvaluateDef object.

• What happens when the event evaluates true, specified via an ActionDef object.

This is described later in more detail with code examples. See Registering interest in an event.

How a client unregisters interest in an Event

A client application can unregister interest in one of two ways:

Use the count property to control when interest is unregistered. There are several ways that you can control the length of your event registration.

• Call the EventRegistration.unregister() method.

NOTE: For event registrations where both the evaluate() and the action() methods live in the WebLogic Server, it is the responsibility of the client to unregister interest. If the action() method lives in the client, then deregistration takes place automatically when the WebLogic client disconnects.

Processing an event

This section describes how event propagation works. Understanding this will help in understanding how to use WebLogic Events in your network applications.

How the Topic Tree is traversed

Any application can submit an event to the WebLogic Server. An event is submitted with a set of event parameters that qualify its scope. Once it is submitted, the WebLogic Server tries to find an exact match for the specific event in the Topic Tree. If found, the EventRegistration(s) for that EventTopic are processed (described next). If no exact match is found, or no clients have registered interest in that EventTopic, then the event is considered as not delivered at this point. Next, the Topic Tree is ascended to the next less-specific EventTopic, and the EventRegistrations there are processed, and so on, until the top of the topic tree is reached.

How each EventRegistration is processed

Each client that has an interest in a particular EventTopic should have registered an EventRegistration with that topic. So, each EventTopic in the Topic Tree has a list of EventRegistrations, which describes how each client is interested in the EventTopic. When an EventTopic is matched to an Event, it processes each EventRegistration in the following way:

• If the EventTopic is an exact match to the Event, the Event is evaluated by the EventRegistration. (i.e. the following conditions are skipped)

• However, If this is a less specific Event Topic than the actual published event. i.e. it is an Event Topic that is higher up the Topic Tree, then the following considerations are made.

  • If the event was not delivered to a more specific EventTopic successfully, it is evaluated by the EventRegistration.

  • If the event was delivered to a more specific Event Topic, then the sink flag of the EventRegistration is considered.

sink

A registration can be flagged as a sink, which means that it is guaranteed to receive a chance to evaluate all events in which it has registered an interest, as well as all events associated with more specific topics below its registration in the Topic Tree. (Registering for the root topic (*) with the sink flag set to true guarantees a chance to evaluate every event submitted to the WebLogic Server. If your evaluate method for such a registration does nothing but return true, you effectively act upon every event submitted to the WebLogic Server.)

If you set a registration's sink flag to false (the default), your client only receives notification when that exact event occurs and not when more specific events below that branch occur. However, there is an exception to this rule:

Even with the sink flag set to false, the EventRegistration evaluates a more specific event if that event was not delivered successfully to a more specific Event Topic. This would happen if no client had registered interest in the more specific Event Topic at that time. Because a topic does not exist in the tree until a client has registered interest in it, you should be careful when evaluating events. Do not assume that setting sink to false ensures your client only receives events exactly related to that topic.

Because events are evaluated this way, you can establish EventRegistrations to catch events that no clients have registered to receive.

How events are evaluated by an EventRegistration

When a client registers interest in an event via an EventRegistration, it must specify an Evaluate object, that is associated with the EventRegistration. Once an event reaches a matching registration, the WebLogic Server calls the Evaluate object's evaluate() method. The Evaluate class, which implements the interface weblogic.event.evaluators.EvaluateDef, is guaranteed to implement this method, and is usually a user written class, or one of the default weblogic evaluators. The Evaluate class must be installed on the server, and must lie in the server's CLASSPATH.

The evaluate() method is passed the parameters that accompany the event. The custom method may analyze the event parameters, and return either true or false. When true, the WebLogic Server, invokes the Action object's action() method, unless phase is set to false.

phase

When a client registers interest in an topic, it may set the phase, which negates the logic that triggers the Action. For example, if an application is interested in when the weather is sunny in San Francisco, the registration will be as follows:

• Topic is weather.northamerica.california.sf

• Evaluate parameters are SKYINDICATOR="fogginess", INDICATORLEVEL="over", and INDICATORVALUE="40%"

• Phase is false

Now that the logic is reversed, the client will be notified when it is not foggy in San Francisco. One would hope this means it is sunny!

How the action process works

If the evaluation process succeeds, the action class for that registration is called.

The Action class is a user-written class, which implements the interface weblogic.event.actions.ActionDef. Your action class can perform any action that can be written in Java. Examples of action classes are the ActionEmail, ActionUDP, and ActionNull included in the weblogic.event.actions package.

An Action class may notify the WebLogic client that issued the registration of interest that the evaluator returned true. See below for an example of client-side notification.

More about parameters

Parameters are used by several objects in the WebLogic Server, including:

• Registration management. Administrative parameters, used for registration management, set limits on how many times the evaluator will be called and other administrative details.

• Registration of interest. Registration parameters are a set of name=value pairs that together define the scope of the interest in an event. With these parameters, the WebLogic Server can filter events to further qualify whether or not an event should be evaluated. A registration is always submitted to the WebLogic Server with a set of registration parameters (that is itself a subset of the registration's administrative parameters).

• Event parameters. Event parameters, like Registration parameters, are a set of name=value pairs that further qualify the event. An event is always submitted to the WebLogic Server with a set of event parameters.

A parameter is constructed as a ParamSet object, which may itself be an array of ParamSets. The value associated with each parameter of a ParamSet is a ParamValue object, which may itself be an array of ParamValues.