OpenAjax Hub Specification v07 PublishSubscribe

From MemberWiki

Jump to: navigation, search

(This wiki page holds a portion of the version 0.7 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.7 (September 3, 2007) draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v07. Version 0.7 is preserved for historical reasons and therefore is out of date.)

(The most current version of the OpenAjax Hub Specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification.

<--previous       contents--^       next-->


Contents

3 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".

Parameters

name
The name of the event to listen for. (See the section below on "Event names".)
callback
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.

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){ ... }

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 names

Event names may use any (Unicode) character permitted by the JavaScript language, but there are various factors that developers need to take into account:

  • The OpenAjax Hub uses the period character (".") as a token separator character (see discussion above about tokenization)
  • Each token within an event name MUST consist of at least one character. For example, the event name "a..b" is invalid because the middle token has no characters.
  • The OpenAjax Hub uses the asterisk character ("*") to indicate wildcards (see discussion above about wildcards).
  • Wildcard specifications MUST appear within a token only as a single "*" or a double "**". For example, the event names org.example.*, org.*.foo, and org.example.** are valid, but the event name aaa.bb*cc MUST NOT be treated as a valid wildcard specification because the "*" is mixed with other characters.
  • A double asterisk wildcard value ("**") MUST NOT appear except as the final token in the event name. For example, org.example.** is valid but org.**.foo MUST NOT be treated as a valid wildcard specification.
  • While any Unicode character permitted by the JavaScript language is valid in an event name, it is recommended that developers SHOULD avoid event names that might lead to human error (e.g., spaces at beginning or end of topic might lead to confusion); prove problematic to automated processing (e.g., quotes, less-than or greater-than symbols are special characters for HTML and XML); or prove problematic for transmission through emails or via system copy/paste facilities (e.g., newline characters). It is therefore recommended that event names avoid the use of control characters (e.g., 0x01), quote characters (single or double quotes), whitespace characters (leading space, trailing space, tabs or newlines), or punctuation characters (e.g., parentheses, less-than, greater-than).
  • To avoid potential event name conflicts with other components, it is recommended that event names begin with a registered internet domain expressed in reverse order, such as org.openajax.registerLibrary.
  • It is recommended that event names are tokenized to maximize usefulness in wildcarding scenarios, while taking into account that there is likely a slight performance impact for names with many tokens (e.g., a.b.c.d.e.f.g.h.i.j might require the Hub invokes 10 levels of recursive function calls)
  • The latest releases of browsers have good support for Unicode, but there are known bugs with Unicode support beyond the ASCII range in previous browser releases. Therefore, if event names include characters outside the ASCII range, be sure to test across all target browsers. (This problem should go away over the course of time.)

Callback function guidelines

Developers need to be aware that the contents of parameter publisherData that is passed to a subscriber callback function might contain references to JavaScript objects, some of which 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, as a general rule, not change its contents. The exception to this general rule is when the documentation for a particular event identifies particular areas within publisherData that is intended to be read-write. For example, perhaps there is a boolean flag in publisherData that is initialized to false and but which callbacks are instructed to set to true in particular situations.

Retrieved from "http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v07_PublishSubscribe"
Personal tools