OpenAjax Hub Specification v04 PublishSubscribe
From MemberWiki
(The most current version of the OpenAjax Hub Specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification.
(This wiki page holds a portion of the version 0.4 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.4 draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_04. Version 0.4 is preserved for historical reasons and is very much out of date. A key point about version 0.4 is that it was the most recent version of the Hub spec before the March 2007 InteropFest.))
Contents
|
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.subscribe()
- OpenAjax.unsubscribe()
- OpenAjax.publish()
FIXME: Need to add text to talk about how the event naming approach is desired to be compatible with DOM3 Events, which support namespaced events, while at the same time offering compatibility with today's browsers that do not yet support DOM3 Events.
APIs
OpenAjax.subscribe(prefix, name, refOrName[, scope, subscriberData, filter])
Allows registration of interest in named events based on library-specific prefix and event name. Global event matching is provided by passing "*" in the prefix and/or name arguments. Optional arguments may be specified for executing the specified handler function in a provided scope and for further filtering events prior to application.
The callback function will receive the following parameters (see OpenAjax.publish() for description of publisherData):
function(prefix, name, subscriberData, publisherData){ ... }
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary(). Can be "*" to match the provided event name across all libraries.
- name
- The name of the event to listen for. Names can be any string. Can be "*" to match all events in the specified toolkit (see prefix). If both name and prefix specify "*", all events in the system will be routed to the registered handler (modulo any filtering provided by filter).
- 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,
windowobject is used. - subscriberData
- Optional, can be null. An arbitrary Object holding extra information that will be passed as an argument to the handler function.
- filter
- A function in the following form that returns true or false to either match or deny a match of the published event. The function will receive the following parameters (see OpenAjax.publish() for description of publisherData):
function(prefix, name, subscriberData, publisherData){ ... }
Return value
None.
Module
This method is part of the "PublishSubscribe" module. (Note: For a discussion of the Hub's modules, see http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Bootstrapping_Modularization_Inclusion.)
OpenAjax.unsubscribe(prefix, name, refOrName[, scope, subscriberData, filter])
Removes a subscription to an event. In order for a subscription to be removed, the values of the parameters supplied to OpenAjax.unsubscribe() must exactly match the values of the parameters supplied to a previous call to OpenAjax.subscribe(). Note that it is possible that one invocation of OpenAjax.unsubscribe() might result in removal of multiple subscriptions.
FIXME: This feature is at least partly speculative at this point because it has not been implemented at this time within the reference implementation at SourceForge.
Parameters
- prefix
- See OpenAjax.subscribe().
- name
- See OpenAjax.subscribe().
- refOrName
- See OpenAjax.subscribe().
- scope
- See OpenAjax.subscribe().
- subscriberData
- See OpenAjax.subscribe().
- filter
- See OpenAjax.subscribe().
Return value
None.
Module
This method is part of the "PublishSubscribe" module. (Note: For a discussion of the Hub's modules, see http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Bootstrapping_Modularization_Inclusion.)
OpenAjax.publish(prefix, name[, publisherData])
Publishes (broadcasts) an event based on a library-specific prefix and event name.
Parameters
- prefix
- The prefix that corresponds to this event. This must be a prefix that has been registered via OpenAjax.registerLibrary().
- name
- The name of the event to listen for. Names can be any string.
- 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.
Module
This method is part of the "PublishSubscribe" module. (Note: For a discussion of the Hub's modules, see http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Bootstrapping_Modularization_Inclusion.)
