OpenAjax Hub 2.0 Specification Introduction

From MemberWiki

Jump to: navigation, search

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

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


1 Introduction

The OpenAjax Hub ("Hub") is an Ajax (JavaScript) library that allows integration of multiple client-side Ajax (i.e., HTML+JavaScript) components within a single Web application. The Hub provides a client-side framework that allows trusted and untrusted components to co-exist within the same Web page and communicate with each other.

A key feature in Hub 2.0 is its "Managed Hub," which allows a host application to isolate untrusted components into secure sandboxes. This forces all communication between components to pass through the host application’s security manager, which allows or denies each publish or subscribe request. As a result, the Managed Hub allows for safe integration of untrusted components such as third-party widgets.

Feature Overview

The Hub provides the following services:

Publish/subscribe APIs

The primary features of the OpenAjax Hub are its publish/subscribe APIs that allow different components to send messages to each other. The pub/sub features in the Hub support the anonymous broadcast of messages within the mashup; publishers are typically unaware of how many subscribers there might be or who might be subscribing. The subscriber APIs allow the use of wildcards in order to subscribe to a range of topics.

(Note: Although the Hub is centered on anonymous message passing, applications can add higher level logic to achieve advanced features such as point-to-point messaging, cross-component property management, and remote procedure calls.)

The Hub specification includes:

  • A simple Unmanaged Hub that allows components within a single browser frame to communicate with each other via publish() and subscribe() APIs without any provisions for isolation or security.
  • A more complex Managed Hub that includes the ability to isolate components into secure sandboxes (e.g., using IFRAMEs with different (sub-)domains). The Managed Hub provides isolation mechanisms that ensure the following:
    • Each sandboxed component cannot access the JavaScript environment or DOM of the host application or other components.
    • The only mechanism by which the sandboxed component can communicate with the host application or other components is by using the Hub's publish() and subscribe() APIs.
    • Security manager callbacks provided by the host application define a custom security policy that controls which components can publish and/or subscribe to which messages.
    • The following security techniques must be implemented in conforming implementations (such as the OpenAjax Alliance open source reference implementation):
      • Component loading and unloading techniques to make sure that the correct component is loaded and continues to run. A conformant implementations must include facilities that are designed to prevent malicious components from injecting themselves as replacements for the originally loaded components. (In other words, the Managed Hub must include anti-frame-phishing capabilities.)
      • Messaging techniques that ensure private communication channels between the host application and each component, so as to prevent malicious components from monitoring messages directed to other components or forging messages towards other components.
      • A means of preventing message forgery, i.e. each Hub component must verify the identity of the component that sent each message.

Ajax library registration APIs

A small part of the Hub provides APIs to allow Ajax libraries to register their presence via a simple API, OpenAjax.hub.registerLibrary(). By registering themselves, the Ajax libraries provide information to the host application that might allow the application to consolidate the use of that library across multiple, independently-developed components.

Reference implementation and test suite

OpenAjax Alliance provides an open source reference implementation for the OpenAjax Hub 2.0 at This open source reference implementation fully implements this specification.

If the reference implementation does not have the characteristics needed for a particular scenario, a different implementation of this specification may be used. OpenAjax Alliance encourages alternate conformant implementations, however with the important requirement that the alternative implementation MUST faithfully implement this entire specification and pass the Hub's test suite.

In addition to holding the reference implementation of the OpenAjax Hub, the open source project holds the official test suite against which implementations of this specification can be tested. The open source project includes test suite documentation.

The open source project is managed by the Members of the OpenAjax Alliance. The public (Members and non-members) is encouraged to participate and contribute. See for information about how to become a contributor.

Future versions and compatibility

It is expected that:

  • Future versions of OpenAjax Hub will include additional features to extend the technical areas where OpenAjax Hub enables Ajax interoperability
  • Future version of OpenAjax Hub will be backwards compatible with this version

Future versions of this specification might add new methods or properties on the OpenAjax object or to the various singleton objects, classes, and interfaces defined by this specification. In order to avoid conflict with future versions of the OpenAjax Hub and other software that might extend the Hub, implementations generally SHOULD NOT store implementation-specific parameters directly on any singletons, classes or interfaces defined by this specification; instead, the recommended best practice is to place implementation-specific parameters on a sub-object (e.g., params.ABCOrg.*) where the sub-object's name (ABCOrg) is unlikely to collide with other implementations. One recommended technique to avoid collisions is for the name of the sub-object to reflect the name of the organization associated with the parameters on the sub-object. (Note that some areas of this specification include special extensibility guidelines for particular topics.)

This version does not utilize the global object OpenAjaxConfig, but that global object might be used for runtime configuration parameters in future versions of the Hub.

As a notational convention, Hub implementers are encouraged to use an underscore prefix for all private methods and sub-objects, to make them easily distinguishable from public methods and objects.

Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

JSDoc Conventions

Some of the APIs defined within this specification use JSDoc commenting conventions to describe various details about a particular API, such as a method's parameters, return values and exceptions. Here is an example that illustrates the use of JSDoc commenting conventions:

 * Returns the client ID of this HubClient
 * @returns clientID
 * @type {String}
OpenAjax.hub.HubClient.prototype.getClientID = function() {}

The JSDoc code above identifies the method name (OpenAjax.hub.HubClient.prototype.getClientID), a description for this method (i.e., "Returns the client ID of this HubClient"), and the value returned by the method (i.e., a JavaScript String object).

This specification uses the following subset of JSDoc: (Note: This subset is designed to align with the JSDoc syntax defined by JSDoc Toolkit version 2.1 (

  • At the bottom of the API definition is the name of the specified interface, in the form of a JavaScript function definition. The function definition shows the parameters to the function, with an empty function body (i.e., the function body is {}).
  • Above the function definition are JavaScript comments that conform to JSDoc document commenting conventions, where the comment begins with the characters /** and ends with the characters */ .
  • Any textual comments that do not begin with a JSDoc tag (A JSDoc "tag" is a keyword that begins with the @ character, such as @param) represent free-form descriptions of the given API.
  • This chapter uses the following JSDoc tags:
    • @param {type} name Description - Specifies a parameter to a function.
    • @returns Description - Specifies the value returned by a function.
      • @type {type} - An @type immediately after an @returns specifies the datatype of the return value.
    • @see Description - Specifies a reference to other documentation.
    • @throws {type} Description - Specifies an exception that a function might throw.
  • Notes:
    • The {type} is an ECMAScript datatype, such as {Object} or {String}. A value of {*} indicates any JavaScript value . A vertical bar represents an OR condition. For example: {Function|String}.
    • The Description is free-form text that provides a textual description. The Description might appear on the same line of the tag and/or might appear on one or more immediately following lines.
  • Optional parameters are defined by surrounding the parameter name in square brackets, as in @param {*} [subscriberData].

When parameters are objects, such as the params object required by OpenAjax.hub.Container:

@param {Object} params

the properties of these objects are specified using separate @param tags:

@param {String} params.IframeContainer.tunnelURI


The following are definitions for terms used within this document:

FIM (fragment identifier messaging)
FIM is a technique for passing messages between iframes by changing the string that follows the "#" character in the window.location.href URL string. For background information on how FIM can be used to achieve secure cross-iframe messaging, refer to the paper "SMash: Secure Component Model for Cross-Domain Mashups on Unmodified Browsers" [1].
Frame phishing
In a web user interface involving multiple iframes or frames, scripts within one frame might try to change the src attributes of other frames to make them point to "phishing sites" that are counterfeit versions of the documents that should be displayed in the frames, and which trick the user into entering sensitive information. This is known as "frame phishing."
When used by itself, the term "Hub" is a shorthand for "OpenAjax Hub".
JSON-serializable value
A JSON-serializable value is a JavaScript data value (e.g., Boolean, Number, Array, Object, etc.) that can be converted, without data loss, to and from one of the following:
  • For JavaScript objects: JSON object notation
  • For JavaScript arrays: JSON array notation
  • For primitive data types: into a JavaScript literal (string, number, true, false, or null).
In particular, any Javascript value that is itself of type Function, or that is an Array or Object value that includes a Function within itself, is not JSON-serializable.
See JSON specification.
Library (in the context of "Ajax library" or "JavaScript library")
A collection of client-side JavaScript runtime logic that provides useful features for Ajax developers.
Same Origin Policy
Modern Web browsers implement a "same origin policy" that permits scripts running on pages originating from the same domain to access each other's methods and properties with no specific restrictions, but prevents access to most methods and properties across pages originating from different domains.
Toolkit (in the context of "Ajax toolkit" or "JavaScript toolkit")
A collection of technologies, products, and other supporting materials such as documentation, that help a customer to produce an Ajax-based solution. In some scenarios, a toolkit might just be a library, but in other cases will consist of some combination of libraries, server components, authoring components, associated utility software, and supporting materials such as documentation.

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