Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

# 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. Contents Introduction WebLogic's Topic Tree Registering interest in a topic Unregistering for a topic Generating an event evaluate() and action() methods in event generation # Introduction 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. # WebLogic's Topic Tree 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 weather.northamerica.us.california.sf. ### How the Topic Tree works The whole event service flows through the Topic Tree. Registrations of interest in specific events are put into the Topic Tree. Events trickle down through the Topic Tree until they reach the registrations corresponding to the topics. Each registration's evaluate() method is called, and if the evaluation succeeds, the action() method is called. 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: EventRegistration operations. An application registers interest in a particular topic (a node in the Topic Tree), by sending an EventRegistration to WebLogic. EventMessage operations. Any application on the network can generate an event for a particular topic, by sending an EventMessage to WebLogic. 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 notification"). ### How topics are arranged 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." ### How events and registrations are qualified 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: Event parameters qualify an EventMessage. An event parameter for a weather event might be a "fogginess" factor. Evaluate parameters qualify specifics about how an event should be evaluated. An evaluate parameter for a weather event might a "fogginess" factor. Action parameters qualify the action. An action parameter might be an email address, if the action is to send an email notification that an event has occurred. 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. # Registering interest in a topic 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: The name of the topic Evaluate and Action objects that instantiate the classes that should be executed for evaluation and action Instructions on how WebLogic Events should manage this registration 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. ## What makes up an EventRegistration There are several parameters that tell WebLogic Events how your event registration should be handled. These include: Topic of interest Evaluate Class Action Class Registration settings Catch-all flag Phase flag Own-thread flag Count ## Topic of interest The 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 classes The 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 Generation." ### Setting parameters for Evaluate and Action objects 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: SKYINDICATOR="fogginess" INDICATORLEVEL="over" INDICATORVALUE="50%" 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: SYMBOL=IBM ANIMAL=FISH DEVICE=PRINTER 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: TRIGGERPARAMETER ="PRICE" TRIGGEROPERATOR ="LESSTHAN" TRIGGERCOMPARATOR="5.00" 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. ## Registration settings ### Catch-all flag The catch-all flag, when true, indicates that this registration is guaranteed to receive notification of every event in which it has registered interest, as well as notification of events in any more specific topics. 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. ### Phase flag 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 reservations. ### Own-thread flag The evaluate() and action() methods are normally invoked in the context of the thread within WebLogic that generated the event. When the own-thread flag is true, a separate thread is created at registration time for this registration's evaluate() and action() methods to run in. If own-thread is false then the evaluate() and action() methods are invoked in the context of the thread that generated the event. ### Count 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. # Unregistering for a topic You can also unregister interest in a topic. There are two methods of unregistering: If you still have a reference to the original registration object, you can use the instance method EventRegistration.unregister() to unregister interest in a topic. Otherwise, use the static method EventRegistration.unregister(), which takes the registration ID which was returned in the original registration as an argument. Setting the count flag will automatically unregister interest in a topic after its has received n events. # Generating an event 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. When an EventMessage is submitted to WebLogic, a topic and a ParamSet that contains the Event parameters are specified. ### Event parameters 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. ### What happens when a registration is notified that an event occurred? 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: weather.northamerica has a default registration. weather.northamerica.ca has a catch-all registration. weather.northamerica.ca.sf has a default registration. 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: weather.northamerica.us.california has a default registration and has several subtopics in the Topic Tree, among which is weather.northamerica.us.california.sf. An EventMessage is received for weather.northamerica.us.california.sf, and the corresponding registration is notified. An EventMessage is received for weather.northamerica.us.california.la, for which there are no registrations. The EventMessage is passed to weather.northamerica.us.california. 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. # evaluate() and action() methods in event generation 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. The Evaluate and Action classes have, respectively, an evaluate() and action() method that are of interest. ### evaluate() method 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." ### action() method 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 database, etc. ### Context in which evaluate() and action() Methods are Invoked 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. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher. Last updated 08/23/1999