OpenAjax Hub 2.0 Specification Unmanaged Hub

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Hub 2.0 Specification.

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


Contents

4 Unmanaged Hub

Unmanaged Hub Overview

The Unmanaged Hub feature within the OpenAjax Hub provides a simple and lightweight publish/subscribe engine that allows trusted components that exist within the same browser frame to send messages to each other. The Unmanaged Hub includes no provisions for component isolation or security; if your application requires component isolation and security features, then use the Managed Hub instead.

The Unmanaged Hub enables JavaScript components (which may include libraries, objects, etc.) to publish events on a broadcast basis and to listen ("subscribe") to events published by other components.

The Unmanaged Hub provides the following functions on the global OpenAjax.hub object:

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

For details about the subset of JSDoc used in this specification, refer to the write-up on JSDoc Conventions in the Introduction chapter.

APIs

OpenAjax.hub.subscribe(name, refOrName, scope, subscriberData) 

/**
 * Creates a subscription on the specified topic name. 
 *
 * @param {String} name
 *     The name of the topic to which you want to subscribe. 
 * @param {Function|String} refOrName
 *     A function object reference or the name of a function 
 *     that is invoked whenever an event is published on the topic.
 * @param {Object} [scope]
 *     An Object in which to execute refOrName when handling the event. 
 *     If null, window object is used. The scope parameter will be the 
 *     "this" object when the callback is invoked.
 * @param {*} [subscriberData]
 *     Client application provides this data, which is handed
 *     back to the client application in the subscriberData
 *     parameter of the callback function.
 * @returns 
 *     A String Object (a "subscription") that is unique for this particular subscription.
 * @type {String}
 */
OpenAjax.hub.subscribe(name, refOrName, scope, subscriberData) {}

This function returns an Object (a "subscription") that is unique for this particular subscription. To unsubscribe, return this Object to OpenAjax.hub.unsubscribe(...). This subscription 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.

Topic names are strings composed of sequences of tokens separated by the "." character (period character - 0x2E). They MAY include wildcard characters. For detailed rules and guidelines on topic names, see Topic Names chapter.

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

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

The callback function does not return a value. The callback function SHOULD NOT throw exceptions.

Hub 1.0 feature no longer available in Hub 2.0

Hub 1.0 included a 5th parameter, 'filter', to OpenAjax.hub.subscribe. This parameter has been removed from the OpenAjax Hub with version 2.0. Below is the description of the (now-removed) 'filter' parameter.

filter
Optional, can be null. A function that returns true or false to either match or deny a match of the published event. The filter function 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 callback function takes the same parameters as the data callback function.

(Note that although this convenience feature have been removed from the OpenAjax Hub 2.0 Specification, it continues to be supported within the open source reference implementation provided by OpenAjax Alliance within a special "Unmanaged Hub" release configuration, which is fully compatible with the Hub 1.0 Specification.)

OpenAjax.hub.unsubscribe(subscription) 

/**
 * Removes a subscription to an event.
 *
 * @param {String} subscription
 *     The return value from a previous call to OpenAjax.hub.subscribe().
 */
OpenAjax.hub.unsubscribe(subscription) {}

This function does not return a value.

OpenAjax.hub.publish(name, publisherData) 

/**
 * Publishes (broadcasts) an event.
 *
 * @param {String} name
 *     The name of the topic that is being published. 
 * @param {*} [publisherData]
 *     (Optional) An arbitrary Object holding extra information that 
 *     will be passed as an argument to the handler function.
 * @type {Object}
 */
OpenAjax.hub.publish(name, publisherData) {}

The name parameter MUST NOT contain wildcard tokens. For detailed rules and guidelines on topic names, see Topic Names chapter.

This function does not return a value.



<--previous       contents--^       next-->
Retrieved from "http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification_Unmanaged_Hub"
Personal tools