WebLogic Events Architecture
This whitepaper describes the architecture of WebLogic TM Events, WebLogic's event notification and management service. WebLogic Events is one of the many facilities that operate within WebLogic. More detailed information on using WebLogic Events is available in the Developers Guide, Using WebLogic Events.
With WebLogic Events, any WebLogic application on the network can register interest in an event. An event might be a move in stock prices or a change in the weather in a particular city; it might be a performance mark on a particular machine somewhere on your network.
Events and registration of interest in events are matched up by the WebLogic Server. When WebLogic receives an event that matches a registration, it executes a user-written evaluate() method, and depending upon the results, executes a user-written action() method. An action might be playing a sound on your PC, sending an email message or fax, or writing a line to a database.
WebLogic Events removes the need for applications to poll at regular
intervals to find out if certain events have taken place. Instead,
the event itself triggers an appropriate action.
The key to the architecture of WebLogic Events is the Topic Tree.
The Topic Tree is a hierarchical, n-ary tree of period-separated
words, where each word represents a node at a particular level in the
tree. Each level in the hierarchy represents a greater level of
specificity; for instance, a typical topic about city weather in San
Francisco might be listed as
Event submission with WebLogic Events, designed to be extremely inexpensive in memory and CPU time, is meant to be an efficient, light-weight mechanism that can and should be used liberally. A judiciously designed Topic Tree, with carefully thought-out registration and event parameters and evaluate() and action() methods, can product an extremely elegant and efficient system for managing data flow in a distributed application.
There are two fundamental groups of operations that can be performed on the Topic Tree:
The core tasks of the WebLogic Events server are to match up EventMessages
with corresponding EventRegistrations, to allow matching
EventRegistrations to evaluate the event, and to allow an
EventRegistration to operate on events which have been evaluated as
being of interest. Event operations, including registration,
evaluation, and actions, take place within WebLogic; actions can
also be executed in registered client (called "client-side
There are two relationships that define how topics are arranged in the Topic Tree; more specific and more general. More specific topics are found further down in the Topic Tree, but within the same sub-tree. Less specific topics will be further up the tree.
In the example shown here, weather.northamerica.us.california.sf is a more specific topic than weather.northamerica, because weather.northamerica.us.california.sf is found within the subtree rooted at weather.northamerica.
The root of the Topic Tree is denoted by * (star). All other topics are considered to be more specific than the root topic, and the root topic is more general than all other topics. A registration for the root topic means that you are interested in all topics. A catch-all registration at the root level guarantees you a copy of every notification. A default registration at the root level guarantees you a copy of all notifications that no other topic accepts.
When WebLogic Events receives an event, it finds the corresponding topic
in the Topic Tree corresponding to the event. All EventRegistrations under
that topic or a more general topic are considered candidate
registrations for notification about the event. The order in which
candidate registrations are processed is from most specific to the
root. This process is described more fully in "Generating an Event."
Events, registrations, evaluations, and actions all use sets of parameters to qualify scope. Parameters are handled in WebLogic Events by weblogic.common.ParamSets objects, which contain weblogic.common.ParamValues.
In general, a parameter is a name/value pair, like SKYINDICATOR="fogginess". The name of a parameter is its keyname, and all ParamSet contents are accessible by keyname. For each keyname in a ParamSet, you set a corresponding ParamValue. A ParamSet may be made up of a vector of ParamSets, and a keyname can be associated with a vector of ParamValues.
There is a ParamSet associated with each EventMessage (event registration). Each EventRegistration (registration of interest in an event) includes Evaluate and Action objects that were each constructed with a ParamSet that qualifies the evaluation of the event and the action to be taken if the evaluator returns true. ParamSets are used specifically in these contexts:
Parameters allow you to specify in detail what interests you about an event. For example, you might register for the topic "stocks" but you might specify as a Evaluate parameter which stocks you are interested in, or what information about certain stocks you are interested in.
In order to receive notification of events and have the opportunity to act upon them, an application must register interest in a topic. In the registration process, you specify three types of information:
You can have multiple registrations for the same topic.
Upon successful registration, a registration ID is returned.
The registration ID may be used later to unregister for this topic.
It can also be used to retrieve certain information from the
WebLogic Server about the registration.
Upon successful registration, a registration ID is returned. The registration ID may be used later to unregister for this topic. It can also be used to retrieve certain information from the WebLogic Server about the registration.
Topic of interestThe topic of interest is a topic anywhere in the Topic Tree. A topic of interest is listed in a string of period-separated words, like an Internet domain name or a Java package name. The Topic Tree is built dynamically by WebLogic Events as new registrations are made.
Evaluate and action classesThe Evaluate and Action classes are user-written Java classes that implement either the weblogic.event.actions.ActionDef or weblogic.event.evaluators.EvaluateDef interfaces, or both. Any Java class can implement the evaluate and action interfaces. When interest in an event is registered, WebLogic Events instantiates an object for the action and evaluate classes. The two most important methods in these classes are evaluate() and action(), because they are used to actually evaluate and act upon the events as they are received.
The classes that are specified in the registration as the evaluate and action classes are dynamically loaded into WebLogic the first time any registration specifies either of them. The constructor for the class that implements the interface(s) must have a default constructor, that is, one that takes no arguments, because the Java class loader does not permit the passing of arguments to the constructors of dynamically loaded classes (see java.lang.Class.newInstance).
Because arguments cannot be passed when the evaluate and action objects are instantiated, another method, the registerInit() method, must be implemented in each class. The registerInit() method, which takes the registration parameters as an input argument, allows the newly constructed evaluate and action objects to inspect and act upon the registration parameters at the time of registration.
Note that in the case where the evaluate class and the action class parameters specify the same class, only one instance of the object is instantiated for that registration, and registerInit() is only called once. Being part of the same class and object allows the evaluate() and action() method to share instance variables.
For more information about evaluate() and action() methods at event generation, see "evaluate() and
action() Methods in Event
The Evaluate and Action objects that are used as arguments to the constructor of an EventRegistration are themselves constructed with a ParamSet, a set of name/value pairs. These parameters qualify interest in a topic. For instance, if you are interested in knowing when it is more than 50% foggy in San Francisco, you might register for the topic weather.northamerica.us.california.sf, with the following set of Evaluate parameters:
Each time a weather-related event for San Francisco is generated, WebLogic Events finds all the registrations for weather.northamerica.us.california.sf and gives each a chance to evaluate the Event parameters against any registrations. In this case, a San Francisco weather event with the Event parameters "fogginess=95%" would evaluate to true for your registration, and the action() method would be called . . perhaps to cancel your airline tickets and hotel reservations.
Names of Evaluate parameters may be the same for many different topics of interest. For instance, the Evaluate parameters "INDICATORLEVEL=over" and "INDICATORVALUE=50%" might apply to weather, stock prices, the cost of eggs in China, the monthly list of economic indicators, or any other kinds of information for which measurement is important.
A typical use of Evaluate parameters would be to filter events with certain qualities, such as:
A more complicated use of parameters would be to have the Event parameters specify the operands and operator of an equation. For example, in a stock ticker application, a registration would specify in its Evaluate parameters the Event parameter name and the Event parameter value as the operands, and the comparison operation that should be performed:
Your evaluate() method would then examine the PRICE Event parameter to see if it is LESSTHAN $5.00.
How the Evaluate and Action parameters are used by the registerInit(), evaluate(), and action() methods is determined by
the programmer. For instance, specifying a fogginess threshold as an
Evaluate parameter for a registration looks for changes in stock
prices would (probably) be meaningless.
If the catch-all flag is not set, the registration
acts as a default for all of its subtopics; that is, it receives
notification of all events with the identical topic as its
registration, plus notification of events posted to more specific
topics in which no more specific registration was notified.
Normally, the action() method is only called if the evaluate() method returns true. Setting phase to false inverts this process; that is, the action() method is called only if the evaluate() method returns false.
For example, if you are interested in knowing when San Francisco
weather is sunny, your application would register an interest in the
topic weather.northamerica.us.california.sf with an event
parameter "fogginess" and with the phase set to false. When the
"foggyEvaluator" method in your application returns false, the action() method will be invoked,
which might do something as simple as sending you email, or perhaps as
elaborate as buying you an airline ticket to San Francisco and making your hotel
Count specifies the number of events that this registration should receive before automatically unregistering itself. Registrations that should not automatically unregister themselves after a certain number of events are processed should specify the symbolic constant weblogic.event.common.EventRegistrationDef.UNCOUNTED for the count parameter.
You can also unregister interest in a topic. There are two methods of unregistering:
Setting the count flag will automatically unregister interest in a topic after its has received n events.
Events are submitted to WebLogic as EventMessage objects. An EventMessage is usually submitted by an WebLogic Events client (in which case the class implements weblogic.event.t3client.EventMessage), although an EventMessage can be submitted to a WebLogic Server by another WebLogic Server (implementing weblogic.event.server.EventMessage), or even by a non-Java application on the network.
Event parameters, like Evaluate and Action parameters, are a set of name-value pairs that further qualify the event, contained in a ParamSet object. Event parameters are often properties of the event that help to qualify the kind or nature of the event.
For example, in topic STOCKS you may have the name/value pair
"SYMBOL=IBM", where SYMBOL is the name and "IBM" is the value, or
"BIDVALUE=100", where BIDVALUE is the name and "100" is the value.
When the WebLogic Events server receives an EventMessage, it finds the topic in the Topic Tree that corresponds to the EventMessage's topic. For instance, when WebLogic Events receives a San Francisco weather event, it will look in the Topic Tree for the topic weather.northamerica.us.california.sf.
Event notification is made to all registrations (whether default or catch-all) that are registered for the identical topic as the event. Notification then proceeds up the Topic Tree towards the root, where a distinction is made between catch-all and default registrations.
More general catch-all registrations are always given notification, and a catch-all registration is therefore guaranteed to receive events notification for its own topic or any more specific topic.
More general default registrations are notified if and only if no more specific registration was notified. As the registrations are examined from the most specific to the root, default registrations are only notified of events only if no more specific topic is notified.
For instance, consider the following scenario:
When an EventMessage for the topic weather.northamerica.us.california.sf is received, registrations #3 and #2 are given a copy of the event, but registration #1 is not, because it is a default, and because the more specific registrations (#2 and #3) were notified.
When an EventMessage for the topic about Los Angeles weather, weather.northamerica.us.california.la, is received, registration #3 does not receive a copy because it does not have the same topic as the event. Registration #2 is notified of the event; therefore, registration #1 does not receive an opportunity to evaluate the event because it is a default and a more specific registration (#2) was notified.
When an EventMessage for the topic weather.northamerica.us.nevada.reno is received, neither registrations #2 nor #3 receives notification because they do not have the same topic as the EventMessage. Registration #1 is notified of the event because it is a default and no more specific registration was notified.
All of the default registrations are treated equally, in the sense that whether or not one gets a notification at a particular level is not dependent upon the event notification's acceptance by any other events at that same level, only by acceptance at a lower, more specific level in the Topic Tree.
The reason why every topic is not a catch-all is so that you can have default registrations. A default registration is one that gets notified of an event for which there no more specific registration. For a registration for which there are no more specific registrations, the behavior of a default and a catchall is identical.
For instance, consider this scenario:
An EventMessage can be distributed to multiple registrations. Once an event has been distributed to at least one registration, no copies will be offered to a more general default registration.
Each registration specifies two classes, both of which are constructed with a ParamSet: an Evaluate class, which contains an evaluate() method that is used to evaluate events for which it is registered, and an Action class, which contains an action() method to be invoked when the evaluate() method accepts the notification. These classes are user-written, and implement the interfaces weblogic.event.evaluators.EvaluateDef and weblogic.event.actions.ActionDef. The user may write a single class that implements both interfaces. In that case only one copy of the class object will be instantiated in WebLogic at registration time.
An evaluate() method indicates that the evaluation was successful by returning a true value.
When you register, you can set the phase for the evaluate() method. A true phase accepts the registration when the evaluate() method returns true. A false phase accepts the notification when the evaluate() method returns false. For example, say you have registered interest in the topic weather.northamerica.us.california.sf, and one of the event parameters is "fogginess." Your application has an evaluate() method called "foggyEvaluator" which returns true if the FOGGINESS event parameter is greater than 50%. Suppose you are interested in being notified on sunny days; your registration will specify the "foggyEvaluator" with a phase of False. When the evaluator's return value matches the phase, the action() method is invoked.
For more information about specifying the evaluate() and action()
methods at registration, see those topics in the section " Registering Interest in a Topic."
An action() method gets a copy of the event and the registration, and
it may perform any function, such as sending email, a page, updating a
By default, the evaluate() and action() methods are invoked in the context of the thread that generated the event. The programmer of the evaluate() and action() methods is responsible for keeping to a minimum the operations that evaluate and take action() on the event, or the programmer must indicate to WebLogic Events that the evaluate/action methods should be invoked from a separate thread. The registration itself can indicate that the evaluate() and action() methods should have a dedicated thread by setting the own-thread flag at registration time.
Specifically, evaluate() and action() methods that are not long-running, i.e., have not asked to run in their own thread, should not take up exhaustive amounts of CPU time and should not block in an I/O operation.
evaluate() and action() methods are user-written.
Copyright © 2000 BEA Systems, Inc. All rights reserved.