OpenAjax Hub 1.1 Specification Unmanaged Hub

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the early draft specification for OpenAjax Hub 1.1. It contains all of the finalized and approved content from the OpenAjax Hub 1.0 Specification, plus draft text for the new features in OpenAjax Hub 1.1. Text repeated from the Hub 1.0 spec isidentified by the string [HUB10]. The draft text for the features that are new to Hub 1.1 is identified by the string [HUB11]. At this point, the new features are very early in development and have received little or no review by the Interoperability Working Group. All of the new features should be treated by the community as a work in progress that is not yet ready for use by the community.

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


Contents

4 Unmanaged Hub

NOTE: So far, the chapter is simply a repeat of the same chapter from the [HUB10] spec.

Unmanaged Hub Overview

NOTE: Need introductory paragraphs to set the context

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.



<--previous       contents--^       next-->
Personal tools