Publish/Subscribe Event Management

Publish/Subscribe Event Management Features

The OpenAjax Hub provides the following APIs for its event management services that enable script logic (from either libraries, components and the application itself) to publish events on a broadcast basis and for script logic to listen (i.e., subscribe) to events fired by other script logic.

OpenAjax.hub.subscribe()
OpenAjax.hub.unsubscribe()
OpenAjax.hub.publish()

APIs

`OpenAjax.hub.subscribe(name, callback, scope, subscriberData, filter)`

Allows registration of interest in named events based on an event name. Event names are expressed as tokens separated by the "." character (period character - 0x2E). For example, the event name "org.openajax.hub.registerLibrary" has four tokens.

There are two options for wildcard event matching:

The "*" wildcard (asterisk character - 0x2A) may be used as a token in any part of the event name. For example, "org.example.module1.*" will subscribe to all events that have four tokens and whose first three tokens match "org.example.module1". Intermediate wildcards are supported. For example, "org.example.*.log" will subscribe to all events that have four tokens where the first two tokens match "org.example" and the fourth token matches "log". Therefore, this wildcard pattern would match either "org.example.type1.log" and "org.example.type99.log". Multiple "*" wildcards are supported within a single event name.
The "**" wildcard (two asterisk characters) may be used as the last token in an event name to match against any event names that share the same root but can have different values after the root. For example, "org.example.**" will be dispatched to all events that have at least 3 tokens where the first two tokens match "org.example". Thus, "org.example.**" matches the following event names: "org.example.foo" and "org.example.foo.bar".

The filter function is optional and allows for the definition of an intermediate function that is invoked before the callback function. Filter functions return a boolean. If the filter function returns false, then the given callback function is not invoked.

The filter and callback functions will receive the following parameters (see OpenAjax.hub.publish() for description of publisherData):

function(name, publisherData, subscriberData){ ... }

Parameters

name: The name of the event to listen for. See discussion above about tokenization and wildcards. FIXME: Need to define allowable character values within an event name.
refOrName: A function object reference or the name of a function to be called when the document is loaded.
scope: Optional. An Object in which to execute refOrName when handling the event. If null, window object is used. scope will be the this object when callbacks are invoked.
subscriberData: Optional, can be null. An arbitrary Object holding extra information that will be passed as an argument to the handler function.
filter: Optional, can be null. A function that returns true or false to either match or deny a match of the published event. See discussion above for more about the filter function.

Return value

Returns an Object (a "subscription") that is unique for this particular subscription. To unsubscribe, return this Object to OpenAjax.hub.unsubscribe(...). This object MUST be treated as an opaque, read-only value by applications and libraries that are using the Hub. Thus, the object MUST NOT be modified or deleted.

`OpenAjax.hub.unsubscribe(subscription)`

Removes a subscription to an event.

Parameters

subscription: The return value from a previous call to OpenAjax.hub.subscribe(...).

Return value

None.

`OpenAjax.hub.publish(name, publisherData)`

Publishes (broadcasts) an event.

Parameters

name: The name of the event that is being broadcast.
publisherData: Optional, can be null. An arbitrary Object holding extra information that will be passed as an argument to the handler function.

Return value

None.

Event name guidelines

(FIXME: Need to discuss how we strongly recommend event names that begin with a registered internet domain expressed in reverse order, such as "org.openajax." and that event names are designed to maximize usefulness in wildcarding scenarios.)

Callback function guidelines

(FIXME: In the general case, developers should be warned that publisherData might contain references to JavaScript objects and therefore some of the values might be live data fields that are critical to other JavaScript logic used within the given Web page. Because of this, callback functions must treat publisherData as read-only and therefore not change the contents publisherData, with the exception that, in certain scenarios, the organization that defines a particular event and its associated publisherData might identify a particular area within publisherData is intended to be read-write. For example, perhaps there is a boolean flag in publisherData that is initialized to false and but which is supposed to be set to true if any of the callbacks meet certain criteria.)

OpenAjax Hub Specification v06 PublishSubscribe

From MemberWiki

Contents

Publish/Subscribe Event Management