From MemberWiki

Contents 1 3 Publish/Subscribe Event Management 1.1 Publish/Subscribe Event Management Features 1.2 APIs 1.2.1 OpenAjax.hub.subscribe(name, callback, scope, subscriberData, filter) 1.2.1.1 Parameters 1.2.1.2 Return value 1.2.2 OpenAjax.hub.unsubscribe(subscription) 1.2.2.1 Parameters 1.2.2.2 Return value 1.2.3 OpenAjax.hub.publish(name, publisherData) 1.2.3.1 Parameters 1.2.3.2 Return value 1.3 Event names 1.4 Undetermined order, asynchronous execution of callback functions 1.5 Do not communicate via exceptions 1.6 Subscriber callback function guidelines 1.7 General guideline: publisher/subscriber independence 1.8 General guideline: read-only publisherData 1.9 Scenario when it is appropriate to have read/write sections in publisherData

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

Undetermined order, asynchronous execution of callback functions

While Hub implementations SHOULD normally deliver messages in a simple time-ordered manner, developers MUST NOT depend on any particular invocation order as a number of different operational factors can impact the order in which messages are delivered.

While Hub implementations SHOULD normally invoke subscriber callback functions as soon as possible, which in some cases translates into immediate execution, developers SHOULD NOT depend on immediate execution of subscriber callback functions as there are various scenarios where subscriber callback functions might execute asynchronously.

Do not communicate via exceptions

Publishers and subscribers SHOULD NOT use exceptions as part of the protocol by which they communicate with each other and share information. Hub implementations are not required to transmit exceptions from subscribers to a given publisher.

As a result, applications that rely on exceptions to communicate responses back to the publisher will not be portable and publishers SHOULD NOT design their events such that subscribers are instructed to throw particular exceptions in particular cases.

Subscriber callback function guidelines

Subscriber callbacks often execute within the single-threaded browser JavaScript context and therefore SHOULD execute and return quickly to prevent the Web page from becoming unresponsive.

Implementations of the OpenAjax Hub are not required to include code to manage exceptions raised by callback functions. If callback functions throw uncaught exceptions, serious side effects might occur, including suspension of execution of JavaScript logic on that page. Therefore, callback functions SHOULD NOT throw uncaught exceptions.

Subscriber callbacks functions MAY invoke other OpenAjax Hub services as part of their processing. For example, they may publish events, even on the same topic name (but beware of infinite recursion). They may also subscribe to topic names, including the same topic name. And they may unsubscribe, including the same subscription or other subscriptions to the same topic name.

Note that all of the same guidelines that ordinarily apply to published events (e.g., general guideline about publisher/subscriber independence) also apply to events published by subscriber callback functions.

General guideline: publisher/subscriber independence

As a general rule, publishers and subscribers SHOULD be designed to operate independently and SHOULD NOT assume that publishers and subscribers share the same JavaScript environment. Publishers SHOULD NOT pass references to JavaScript objects within publisherData and instead pass the values of those objects.

General guideline: read-only publisherData

Developers need to be aware that the contents of parameter publisherData that is passed to a subscriber callback function SHOULD be passed by value (see general guidelines above). However, in some scenario's (see next section) some of the publisher data might be references to objects which might be live data fields that are critical to other JavaScript logic used within the given Web page. Because of this, callback functions SHOULD treat publisherData as read-only and therefore, as a general rule, not change its contents.

Scenario when it is appropriate to have read/write sections in publisherData

In certain workflows where the developer has full control of the execution context, it can be appropriate to loosen the two general rules above (i.e., publisher/subscriber independence and read-only publisherData). One scenario is when the developer knows that the publisher logic and subscriber logic share the same JavaScript environment, such as operating within the same browser frame, and that subscriber callbacks are invoked and return synchronously (i.e., immediate execution). In this case, subscriber callback functions MAY modify particular areas within publisherData that have been documented 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.