View source

<center>[[OpenAjax Hub 1.0 Specification | &lt;--previous]]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[[OpenAjax Hub 1.0 Specification | contents--^]]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[[OpenAjax Hub 1.0 Specification Libraries | next--&gt;]]</center>
<br>

= 1 Introduction =

== Target use cases ==

There is great diversity among the requirements of Ajax application developers, and as a result there is great diversity in the architecture and features in the 200+ Ajax products in the marketplace today. For some developers, the most important factor will be finding an Ajax toolkit that offers strong integration with back-end servers. For other developers, the most important factor will be the availability of particular client-side components (e.g., a rich data grid widgets or an interactive charting widget). As a result, the Ajax ecosystem has developed such that most of the time the developer can find an Ajax toolkit that matches each particular requirement, but often the developer finds that he must mix and match multiple Ajax toolkits within the same Web application in order to address all of his requirements.

The Hub provides standard JavaScript that, when included with an Ajax-powered Web application, promotes the ability for multiple Ajax toolkits to work together on the same page. The central feature of the OpenAjax Hub is its publish/subscribe event manager (the “pub/sub manager”), which enables loose assembly and integration of Ajax components. With the pub/sub manager, one Ajax component can publish (i.e., broadcast) an event to which other Ajax components can subscribe, thereby allowing these components to communicate with each other through the Hub, which acts as an intermediary message bus.

The umbrella use case for the OpenAjax Hub is the set of scenarios in which an Ajax developer needs to deploy a single application that uses multiple Ajax libraries simultaneously. Here are some specific scenarios:

; Your favorite Ajax library does not address all requirements
: In some cases, an Ajax developer might choose to build the majority of his applications using one particular Ajax library, but discovers that the library lacks a particular feature that he needs, and therefore would like to integrate a component from a different Ajax library. In other cases, most of the application might be (non-Ajax) DHTML, but the developer would like to incorporate two components of Ajax technology into the  application, where the two components come from different Ajax libraries.
; Mashups
: A developer (or end user) is likely to find that the different components participating in the mashup are based on different Ajax libraries.
; Portals
: Just as with mashups, it is likely that different Ajax-powered portlets will be based on different Ajax libraries.
; Preference for a loosely coupled application architecture
: The Hub’s pub/sub engine provides an industry-standard approach for a simple, loosely coupled Ajax component integration facility within a Web page. Because the Hub’s pub/sub engine is independent of particular toolkits, implementing to the Hub can sometimes provide modularization benefits that might allow for modular replacement of some technologies used within a given Web page.

== Requirements ==

The following are the requirements which the OpenAjax Hub attempts to address. These requirements might conflict among themselves and therefore tradeoffs need to be made. The order of the requirements below does not reflect any particular order of importance.

# MUST address the most important Ajax library interoperability issues
# Specifications and implementations MUST be royalty-free open technologies
# MUST be as lightweight as possible
# MUST require as few changes to existing Ajax libraries as possible
# MUST have an initial version available to the Ajax community on as fast a timescale as possible
# MUST be simple from an end-user perspective
# MUST support both the Single-DOM and Dual-DOM approaches for Ajax toolkits (as described in the [/White%20Papers.html OpenAjax Alliance's white papers])
# MUST include a robust, forward-looking approach to versioning for both the OpenAjax Hub and the Ajax libraries.
# MUST take into account the realities about limitations in today's browsers, such as poor XML namespace support in some popular browsers

== Features ==

Version 1.0 of the OpenAjax Hub includes the following two key features for Ajax interoperability:

* '''Ajax library loading and unloading control''' - The Hub provides APIs for registering libraries, unregistering libraries, and querying about previously registered libraries.
* '''Publish/Subscribe Event Hub''' - The Hub provides an event hub using a publish/subscribe approach allows libraries to publish and subscribe to events in a reliable manner in order to coordinate actions across components from different Ajax libraries.

== One scenario ==

Let's suppose we have a business intelligence application that uses the following Ajax runtime libraries:

* UTILS.js: Provides highly useful extensions to the browser’s JavaScript environment, such as XMLHttpRequestAPIs
* CALENDAR.js: Provides a calendar widget
* CHARTS.js: Provides a charting widget
* DATAGRID.js: Provides an interactive data grid widget

Let’s assume that the application has a single calendar widget that allows the user to pick a particular date or date range. Along with the calendar, there are various data visualization components in the form of chart widgets (such as a variety of bar charts for daily status, weekly status, monthly status, and yearly status) and data grid widgets (such as selectors for regional data versus national data, both with user-selected columns of interest). Whenever a new date or date range is selected in the calendar widget, the various user-specified visualization components – that is, the charts and/or data grid widgets – need to be updated.

One way to implement this application is to load the JavaScript for the OpenAjax Hub before the other Ajax libraries. For example:

<pre>
&lt;html&gt;
  &lt;head&gt;
    ...
     &lt;script type="text/javascript" src="OpenAjax.js"/&gt;
     &lt;script type="text/javascript" src="UTILS.js"/&gt;
     &lt;script type="text/javascript" src="CALENDAR.js"/&gt;
     &lt;script type="text/javascript" src="CHARTS.js"/&gt;
     &lt;script type="text/javascript" src="DATAGRID.js"/&gt;
    ...
  &lt;/head&gt;
  ...
</pre>

''(Note: Some Ajax runtimes will include the OpenAjax Hub as part of their standard distribution, in which case, so long as the given Ajax runtime's JavaScript is loaded before other OpenAjax-compatible runtimes are loaded, it might not be necessary to include a separate <code>&lt;script&gt;</code> element for OpenAjax.js.)''

To make the application work, the developer registers a callback function that is invoked whenever the user selects a new date in the calendar widget. This callback function then broadcasts the new date event using the OpenAjax Hub's publish() function:

<pre>
    &lt;script type="text/javascript"&gt;
      ...
      // Somewhere in earlier JavaScript code, you need to invoke 
      // the calendar widget's APIs to register MyCalendarCallback 
      // as the callback function for when a new date is selected
      ...
      function MyCalendarCallback(...) {
        // Publish (i.e., broadcast) the "org.example.newdata" event via the OpenAjax Hub.
        OpenAjax.hub.publish("org.example.newdate", newdate);
      }
      ...
    &lt;/script&gt;
</pre>

Then the developer includes code such that each chart widget and data grid widget subscribes to the new date event and provides a callback function. The various callback functions then update the given visualization widget appropriately:

<pre>
    &lt;script type="text/javascript"&gt;
      ...
      function SubscribeNewDateCallback(eventname, publisherData, subscriberData) {
        ...
        // Update the given visualization widget
        ...
      }
      // Subscribe to (i.e., listen for) any "org.example.newdata" events via the OpenAjax Hub.
      OpenAjax.hub.subscribe("org.example.newdate", SubscribeNewDateCallback);
      ...
    &lt;/script&gt;
</pre>

== Examples ==

Links to various examples that use OpenAjax Hub 1.0 to integrate multiple Ajax libraries within a single Web application can be found on the following wiki page:

* /member/wiki/OpenAjaxHub_1.0_Examples

== OpenAjax Conformance ==

OpenAjax Conformance is a general term defined at the OpenAjax Alliance Web site () that defines requirements on various aspects of Ajax application development in order to promote interoperability and openness in the Ajax ecosystem and the ability to integrate multiple Ajax technologies within the same Web application. 

The OpenAjax Alliance recommends that Web developers and IT professionals demand OpenAjax Conformance as an industry requirement from its Ajax technology providers. By requiring OpenAjax Conformance, customers gain confidence in their technology and product choices and realize benefits in terms of the ability to integrate Ajax technologies from multiple suppliers, ability to change suppliers at reduced costs, and increased certainty that their suppliers are adopting industry best practices.

The primary focus of this specification is on Ajax libraries and the Ajax applications that take advantage of the libraries. This specification includes various OpenAjax Conformance requirements for libraries and applications. For a library or application to be OpenAjax 1.0 Conformant, it MUST support all of the relevant conformance requirements included in this specification.

Conformance requirements appear in this specification using the following format:

=== <span style="color:green; background-color:#FFE;margin-left:1em">''OpenAjax Conformance Requirement (&lt;category&gt;): &lt;name&gt;''</span> ===
<span style="background-color:#FFE;margin-left:1em;">Subsequent text explains conformance requirement &lt;name&gt;, which applies to category &lt;category&gt;, where : &lt;category&gt; might be ''library'' or ''application''.</span>

== Overview of how the OpenAjax Hub typically is used within an application ==

The following are two typical scenarios for how OpenAjax Hub is used within an Ajax application:

=== Application loads a standalone version of <code>OpenAjax.js</code> before other Ajax libraries ===

In this scenario, the application's HTML file loads a single-file distribution (in the example below, <code>OpenAjax.js</code>) of the OpenAjax Hub by including a &lt;script&gt; tag that references this file before other &lt;script&gt; tags for other Ajax libraries. For example:

<pre>
[01]&lt;html...&gt;
[02]  &lt;head&gt;
[03]    &lt;script src="scripts/openajax1.0/OpenAjax.js" type="text/javascript"&gt;&lt;/script&gt;
[04]    &lt;script src="scripts/foolib1.5/foo.js" type="text/javascript"&gt;&lt;/script&gt;
[05]    &lt;script src="scripts/barlib0.7/bar.js" type="text/javascript"&gt;&lt;/script&gt;
[06]    &lt;script src="scripts/myapp.js" type="text/javascript"&gt;&lt;/script&gt;
[07]  &lt;/head&gt;
[08]  &lt;body&gt;
[09]    &lt;!-- Application-specific HTML markup goes here --&gt;
[10]  &lt;/body&gt;
[11]&lt;/html&gt;
</pre>

The above example assumes that the application uses the OpenAjax Hub along with two OpenAjax Conformant Ajax libraries (version 1.5 of the "foo" Ajax library and version 0.7 of the "bar" Ajax library), all of which have been installed on the same Web server that the application is installed. Because "foo" library and "bar" library are OpenAjax Conformant, these libraries:

* Register themselves with the Hub, providing metadata for the library such as version number
* Subscribe as appropriate to events managed by the Hub's publish/subscribe event manager

In the example above:
* line [03]: the application loads the JavaScript source code for the OpenAjax Hub
* lines [04] and [05]: the application loads the JavaScript source code for two OpenAjax Conformant Ajax libraries (foo and bar)
* line [06]: the application loads its own application-specific JavaScript.

=== Application loads an Ajax library that include the Hub within it ===

In this scenario, the application is using an Ajax runtime library that includes an implementation of the OpenAjax Hub within its distribution. For example:

<pre>
[01]&lt;html...&gt;
[02]  &lt;head&gt;
[03]    &lt;script src="scripts/foolib1.5/fooWithOpenAjaxHub.js" language="JavaScript" type="text/javascript"&gt;&lt;/script&gt;
[04]    &lt;script src="scripts/barlib0.7/bar.js" language="JavaScript" type="text/javascript"&gt;&lt;/script&gt;
[05]    &lt;script src="scripts/myapp.js" language="JavaScript" type="text/javascript"&gt;&lt;/script&gt;
[06]  &lt;/head&gt;
[07]  &lt;body&gt;
[08]    &lt;!-- Application-specific HTML markup goes here --&gt;
[09]  &lt;/body&gt;
[10]&lt;/html&gt;
</pre>

The key things in this scenario are:

# Make sure that the Ajax library that includes the OpenAjax Hub is loaded before the other Ajax libraries
# Make sure that the version of the implementation of the OpenAjax Hub that is included first has all of the features needed by the other Ajax libraries used within the application. (For example, if "foo 1.5" includes version 1.0 of the OpenAjax Hub, but "bar 0.7" requires version 1.2, then the above source code may not work because the version of the Hub embedded within "foo 1.5" may not include the features needed by "bar 0.7".)

== Overview of how libraries typically interact with the OpenAjax Hub ==

A library that is OpenAjax Conformant:

* MAY implement the OpenAjax Hub feature set within the library itself (either by including the reference implementation from http://sourceforge.net/projects/openajaxallianc within the library or by including a different implementation of the Hub) or
* check to see if the Hub has been previously loaded within the given application by an earlier <code>&lt;script&gt;</code> element, and if so, use that version of the Hub

If a library does not include its own version of the Hub, then it might include logic similar to the following: (Note: For conceptual simplicity, the logic below does not check return values or handle exceptions.)

<pre>
if (typeof OpenAjax != "undefined") {
  // The OpenAjax object exists, so use it.
  OpenAjax.hub.registerLibrary(prefix,...); // Register library's prefix, namespaceURI, etc.
  OpenAjax.hub.subscribe(prefix,...);       // Register callback for when particular events occur 
} else {
  // The OpenAjax object does not exist, so don't use the Hub; instead,
  // perhaps the library uses its own publish/subscribe system.
}
</pre>

== Prefixes and Namespace URIs ==

The OpenAjax Hub assumes that each library defines its own unique ''prefix'' and ''namespace URI''. 

=== <span style="color:green; background-color:#FFE;margin-left:1em;">''OpenAjax Conformance Requirement (Libraries): Prefix and Namespace''</span> ===

<span style="background-color:#FFE;margin-left:1em;">To be OpenAjax Conformant, a library MUST define its own unique ''prefix'' and ''namespace URI''. These two values MUST be passed as parameters to <code> OpenAjax.hub.registerLibrary()</code> (see /member/wiki/OpenAjax_Hub_Specification_Libraries). The ''prefix'' specifies a short name for the given library and the ''namespace URI'' holds a URI reference that uniquely identifies the library. ''prefix'' and the ''namespace URI'' MUST conform to W3C rules for namespace prefixes and URI references as defined in [http://www.w3.org/TR/REC-xml-names/ Namespaces in XML]. </span>

If an Ajax library's documentation contains a section on OpenAjax Conformance and/or compatibility with the OpenAjax Hub, that documentation SHOULD specify the parameters that are passed to <code>OpenAjax.hub.registerLibrary()</code> (i.e., ''prefix'', ''namespace URI'', version information, etc.).

== Multiple Usage ==

When a developer integrates multiple independent Ajax components within a given Web page, sometimes multiple components use the same Ajax library.

=== <span style="color:green; background-color:#FFE;margin-left:1em;">''OpenAjax Conformance Requirement (Libraries): Multiple Usage''</span> ===
<span style="background-color:#FFE;margin-left:1em;">To be OpenAjax Conformant, libraries MUST provide a reasonable approach to application developers for addressing the possibility that the given library might be used multiple times within the same Ajax application, such as mashups where different mashup components use the given library multiple times (either same version of the given library or different versions of the given library).</span>

There are multiple ways that an Ajax library can satisfy the above conformance requirement. One relatively simple approach is to have new releases maintain full backwards compatibility with older releases and instruct the developer to ensure to load a version of the Ajax library which is a high-enough revision to support the requirements of all components on the page.

Some Ajax libraries might find it is difficult or impossible to allow multiple usage due to their architecture. For example, an Ajax library that serves as a top-level UI manager of a Web page might have difficulty allowing another instance of itself within the same Web page. Therefore, it is reasonable in ''some'' scenarios for libraries to disallow multiple usage scenarios so long as this restriction is highlighted to the application developer, possibly with notes within the library's documentation or some sort of run-time notification to the developer, such as an error message.

If an Ajax library's documentation contains a section on OpenAjax Conformance and/or compatibility with the OpenAjax Hub, that documentation SHOULD describe how the given library addresses the above multiple usage conformance requirement.

== OpenAjax Hub's Prefix, Namespace, Global Objects, and Multiple Usage ==

OpenAjax Hub is itself a library. Its prefix, namespace and global objects are:

; Prefix
: <tt>OpenAjax</tt>
; Namespace
: http://openajax.org/hub
; Global objects
::; <tt>[window.]OpenAjax</tt>
::: All changes to the JavaScript runtime environment from the OpenAjax Hub are contained within the <tt>[window.]OpenAjax</tt> object.

To address the multiple usage conformance requirement: (see above: OpenAjax Conformance Requirement (Libraries): Multiple Usage)

* Future versions of the OpenAjax Hub specification will be backwards compatible with previous specifications
* Implementations of the Hub MUST have their loading logic (i.e., the Hub's JavaScript logic that gets eval'd when the &lt;script&gt; element is processed) check to see if another implementation of the Hub has already been loaded, and if so, MUST NOT remove, replace, or otherwise modify any of the objects associated with the existing Hub, and MUST NOT install or initial itself within the JavaScript environment
* Libraries or components that have a requirement for a particular version of the Hub MUST check the currently installed version of the Hub and produce an appropriate error if the currently installed version does not support the features it needs. Expressed as a conformance requirement:

=== <span style="color:green; background-color:#FFE;margin-left:1em;">''OpenAjax Conformance Requirement (Libraries): Verify Hub Version''</span> ===
<span style="background-color:#FFE;margin-left:1em;">To be OpenAjax Conformant, libraries that require a particular version of the OpenAjax Hub MUST check that the currently installed version of the Hub matches its requirements, and if not, produce an appropriate error.</span>

=== Loading Requirements on the OpenAjax Hub ===

There are common Ajax application scenarios where a given Ajax application loads multiple Ajax libraries. In these scenarios, it is possible that the underlying JavaScript logic might attempt to load multiple instances of the Hub. 

==== Only first version of the Hub must be loaded ====

In all cases, once one version of the OpenAjax Hub has been loaded, all other instances of the Hub MUST NOT initialize themselves nor alter the version of the Hub that is already present. Thus, the version of the Hub that is loaded by the earliest <code>&lt;script&gt;</code> element MUST be the one used by all Ajax libraries within the application.

Here is an example that indicates how an implementation of the Hub might prevent itself from initializing itself when a version of the Hub is already present:

<pre>
// Only create window.OpenAjax if it does not already exist
if (typeof window.OpenAjax == "undefined") {
  OpenAjax = {
    implementer: "http://openajaxallianc.sourceforge.net",
    implVersion: "1.0",
    specVersion: "1.0",
    ...etc...
}
</pre>

==== Hub implementation mixing disallowed ====

JavaScript logic from one Hub implementation MUST NOT be mixed with JavaScript logic from another implementation.

==== What if different libraries include different versions of the Hub? ====

As mentioned earlier, when a given Ajax application loads multiple Ajax libraries, it is possible that the underlying JavaScript logic might attempt to load multiple instances of the Hub. Furthermore, it is possible that the first library to load the Hub might use an earlier version of the Hub than libraries that are loaded later. To illustrate this scenario, suppose the application uses two Ajax libraries, foolib and barlib, with foolib loaded first, and that foolib includes OpenAjax Hub version 1.0 and barlib includes OpenAjax Hub version 1.1. Since the first instance of the Hub that is loaded prevents other instances from loading, the result is that barlib may not work properly because it requires version 1.1, whereas version 1.0 instead will have been loaded.

One way to address this situation is for the application developer to explicitly load an implementation of the OpenAjax Hub before either foolib or barlib are loaded by including a <code>&lt;script&gt;</code> element that loads the necessary version of the Hub before foolib is loaded. As a result, the lower-version implementation of the Hub within foolib will not load itself.

== Reference implementation and test suite ==

OpenAjax Alliance provides an open source reference implementation for the OpenAjax Hub
at http://openajaxallianc.sourceforge.net. This open source reference implementation
is designed to fully implement the features within this specification, with the intent
that the reference implementation would be suitable for many Ajax application development
scenarios. 

If the reference implementation at http://openajaxallianc.sourceforge.net does not have the 
characteristics needed for a particular scenario, a different implementation
of this specification definitely MAY be used. In fact, OpenAjax Alliance encourages
alternate compatible 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 at http://openajaxallianc.sourceforge.net 
holds the official test suite against which implementations of this
specification can be tested. Test suite documentation is available within 
the set of files within the Hub's open source project at http://openajaxallianc.sourceforge.net.

Despite the fact that the open source project is managed by the Members of the OpenAjax Alliance, the public is encouraged to participate and contribute to the open source project. See http://openajaxallianc.sourceforge.net/ 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 <code>OpenAjax</code>  object. Because of this, to prevent future compatibility problems, implementations of the Hub MUST NOT define extension features to the Hub by means of new methods or properties on the <code>OpenAjax</code> object. The complete definition of the <code>OpenAjax</code> object is controlled by future versions of the OpenAjax Hub Specification published by the OpenAjax Alliance.

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

Implementations of the OpenAjax Hub MAY add private, implementation-specific methods and properties on the <code>OpenAjax</code> object by choosing names that begins with an underscore ("_"), but these methods and properties MUST NOT be designated as public APIs.

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

== Terminology ==

The following are definitions for terms used within this document:

; Dual-DOM
: Some Ajax libraries adopt a Dual-DOM approach that separates the data for the Ajax-related markup into an "Ajax DOM" tree that is kept separate from the "Browser DOM" tree. (See /White%20Papers.html)
; Hub
: When used by itself, the term "Hub" is a shorthand for "OpenAjax Hub".
; library (in the context of "Ajax library")
: A collection of client-side JavaScript runtime logic that provides Ajax services.
; Single-DOM
: Some Ajax libraries use a Single-DOM approach where the library uses the browser's DOM for any original source markup and any HTML+JavaScript that results from the toolkit's Ajax-to-HTML transformation logic. (See /White%20Papers.html)
; toolkit (in the context of "Ajax 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.

<br>
<center>[[OpenAjax Hub 1.0 Specification | &lt;--previous]]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[[OpenAjax Hub 1.0 Specification | contents--^]]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[[OpenAjax Hub 1.0 Specification Libraries | next--&gt;]]</center>