From MemberWiki

Jump to: navigation, search

(This wiki page holds a portion of the version 0.6 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.6 (July 8, 2007) draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v06. Version 0.6 is preserved for historical reasons and therefore is out of date.)

(The most current version of the OpenAjax Hub Specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification.

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

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, which enables loose assembly and integration of Ajax components. Some components publish events using the OpenAjax Hub to which other components subscribe, thereby allowing these components to communicate with each other through the Hub, which acts as an intermediary message bus.

A key umbrella use case for the OpenAjax Hub is the set of scenarios where an Ajax developer needs to deploy a single application that uses multiple Ajax libraries simultaneously. Key use cases for the Hub is portals and mashups, where the application developer creates a page of loosely assembled pre-packaged application components. Portals and mashups typically pull in Ajax-powered components that are built using multiple different Ajax toolkits.

The following are some of the scenarios where developers will find a need for using multiple Ajax libraries simultaneously:

Ajax developer finds that a single Ajax library does not meet all of his requirements: In some cases, an Ajax developer might choose to build the majority of his application using a particular Ajax library, but discover that a particular component from that library does not have the features he needs, and therefore would like to incorporate a component from a different Ajax library, leaving the rest of the application unchanged. 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: In order to build a composite application from pre-existing application components, a developer (or end-user) is likely to have to combine components based on different Ajax libraries.
Portals: Portals support Ajax technologies and represent a variation on composite applications. It is common that different portlets use different Ajax libraries.
Ajax developer sees value in the OpenAjax Hub's publish/subscribe mechanisms: The OpenAjax Hub's pub/sub engine provides an industry standard approach for 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 use within a given Web page. Therefore, the Hub might be attractive to some developers who recognize either the architectural or maintainability benefits from using the Hub.

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

The Hub's publish/subscribe manager

The Hub's key feature is its publish/subscribe manager (the "pub/sub manager"). The pub/sub manager allows one part of a mashup to broadcast an event to which other application components subscribe. For example, suppose there is a calendar widget that allows the user to pick a particular date. The mashup might have multiple UI components that need to update their visual appearance whenever a new calendar date is chosen. In this case, the calendar widget would publish a "new calendar date" event to which the other visualization widgets would subscribe. Therefore, the pub/sub manager's generic messaging benefits is a key integration mechanism between components built from different Ajax toolkits.

(Note: The Hub's pub/sub manager offers various advanced features, such as strong support for wildcards within event names, that are not shown in the example below.)

One scenario

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

UTILS.js, which provides highly useful extensions to the browser's JavaScript environment, such as XMLHttpRequestAPIs
CALENDAR.js, which provides a calendar widget
CHARTS.js, which provides a charting widget
DATAGRID.js, which provides an interactive data grid widget

The application has a single calendar widget and the ability for the user to choose among a number of data views in the form of chart widgets (e.g., bar charts for daily status, weekly status, monthly status, and yearly status) and data grid widgets (e.g., regional data versus national data, both with user-selected columns of interest). Whenever a new date is selected in the calendar widget, the various user-specified visualization components (i.e., 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:

<html>
  <head>
    ...
     <script type="text/javascript" src="OpenAjax.js"/>
     <script type="text/javascript" src="UTILS.js"/>
     <script type="text/javascript" src="CALENDAR.js"/>
     <script type="text/javascript" src="CHARTS.js"/>
     <script type="text/javascript" src="DATAGRID.js"/>
    ...
  </head>
  ...

(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 <script> 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:

    <script type="text/javascript">
      ...
      // 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);
      }
      ...
    </script>

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:

    <script type="text/javascript">
      ...
      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);
      ...
    </script>

OpenAjax Conformance

OpenAjax Conformance is a general term defined at the OpenAjax Alliance Web site (http://www.openajax.org) 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. Because of this, this specification includes various OpenAjax Conformance requirements for libraries and applications, which appear in the following format:

OpenAjax Conformance Requirement (<category>): <name>

Subsequent text explains conformance requirement <name>, which applies to category <category>, where : <category> might be library or application.

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

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

Application loads a standalone version of `OpenAjax.js` before other Ajax libraries

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

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

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
Register the JavaScript global variables that they use with the Hub
Register all 'load' and 'unload' handlers on the HTML <body> element with the Hub instead of registering these handlers directly with the browser
Subscribe as appropriate to events managed by the Hub's publish/subscribe event manager
Register callbacks as appropriate for the Hub's markup scanner

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:

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

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

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

Prefixes and Namespace URIs

The OpenAjax Hub assumes that each library defines its own unique prefix and namespace URI. These two values MUST be passed as parameters to OpenAjax.hub.registerLibrary() . The prefix holds 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 Namespaces in XML.

OpenAjax Conformance (Libraries): Prefix and Namespace

Not yet written.FIXME: Talk about how library must define a prefix and a namespace URI. Both must be compatible with XML Namespaces. Might put this write-up within an OpenAjax section of their documentation.

WE ARE TALKING ABOUT DELETING THE FOLLOWING TEXT. SEE ISSUE 16:
The Hub requires that the application developer MUST provide an xmlns:prefix=namespaceURI declaration (typically on the <html> element) for all libraries used within a given application, where prefix and namespaceURI match the library's documentation. EDITORIAL NOTE: Need to clean up this wording and talk about why this is all necessary (in preparation for future browser support of XHTML, but dealing with today's world where most Ajax is delivered as HTML4).

WE ARE TALKING ABOUT DELETING THE FOLLOWING CONFORMANCE REQUIREMENT. SEE ISSUE 16.

OpenAjax Conformance (Applications): Namespace Declaration

Not yet written.FIXME: Talk about how application developer needs to include xmlns declarations for all OpenAjax Conformant libraries that they use in their application.

Multiple Usage

FIXME: The wording below has proven confusing to some implementers. The original notion when these words were written were that there would be flexibility here about various ways to be conformant, but the bottom line is that it must be possible for the developer to create a mashup that uses multiple components where some of those components might use identical Ajax libraries and some components might use different revisions of a given Ajax library.

OpenAjax Conformance Requirement (Libraries): Multiple Usage

To be OpenAjax Conformant, libraries MUST provide a mechanism for addressing the possibility that the given library might be used multiple times within the same Ajax application (either same version of the given library or different versions of the given library).

To be OpenAjax Conformant, a library must define and document how application developers address situations where a given library might be used multiple times within the same Ajax application (directly or indirectly due to possibly using different components that each use the same library), and thus offering the potential that a given library might be loaded multiple times via different <script> tags. Related to this are scenarios where different components might use different versions of the same library.

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

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

Prefix: OpenAjax
Namespace: http://openajax.org/hub
Global objects [window.]OpenAjax Except for the configuration options found on [window.]OpenAjaxConfig, all changes to the JavaScript runtime environment from the OpenAjax Hub are contained within the [window.]OpenAjax object. [window.]OpenAjax* Not sure about this one. There is discussion relative to the OpenAjax Registry that libraries might be able to reserve all global names that begin with a particular set of letters. If so, then we might want to reserve all globals that begin with "OpenAjax". One global variable that we used to have in earlier versions of the Hub spec was OpenAjaxConfig. Maybe that will be restored in the future.

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 <script> 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:

OpenAjax Conformance Requirement (Libraries): Verify Hub Version

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.

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 load via a <script> element 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 <script> 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:

if (typeof window.OpenAjax == "undefined") {
	OpenAjax = {
		implementer: "http://openajaxallianc.sourceforge.net",
		implVersion: "1.0",
		specVersion: "1.0",
                ...etc...
}

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 <script> 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 OpenAjax 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 OpenAjax object. The complete definition of the OpenAjax object is controlled by future versions of the OpenAjax Hub Specification published by the OpenAjax Alliance.

This version does not utilize global object OpenAjaxConfig, 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 OpenAjax 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 original "Browser DOM" tree.
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.
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.

OpenAjax Hub Specification v06 Introduction

From MemberWiki

Contents

Introduction

Target use cases

Requirements

Features

The Hub's publish/subscribe manager

One scenario

OpenAjax Conformance

OpenAjax Conformance Requirement (<category>): <name>

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

Application loads a standalone version of `OpenAjax.js` before other Ajax libraries

Application loads an Ajax library that include the Hub within it

Overview of how libraries typically interact with the OpenAjax Hub

Prefixes and Namespace URIs

OpenAjax Conformance (Libraries): Prefix and Namespace

OpenAjax Conformance (Applications): Namespace Declaration

Multiple Usage

OpenAjax Conformance Requirement (Libraries): Multiple Usage

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

OpenAjax Conformance Requirement (Libraries): Verify Hub Version

Loading Requirements on the OpenAjax Hub

Only first version of the Hub must be loaded

Hub implementation mixing disallowed

What if different libraries include different versions of the Hub?

Reference implementation and test suite

Future versions and compatibility

Notational Conventions

Terminology

Views

Personal tools

Navigation

Search

Toolbox

OpenAjax Hub Specification v06 Introduction

From MemberWiki

Contents

Introduction

Target use cases

Requirements

Features

The Hub's publish/subscribe manager

One scenario

OpenAjax Conformance

OpenAjax Conformance Requirement (<category>): <name>

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

Application loads a standalone version of OpenAjax.js before other Ajax libraries

Application loads an Ajax library that include the Hub within it

Overview of how libraries typically interact with the OpenAjax Hub

Prefixes and Namespace URIs

OpenAjax Conformance (Libraries): Prefix and Namespace

OpenAjax Conformance (Applications): Namespace Declaration

Multiple Usage

OpenAjax Conformance Requirement (Libraries): Multiple Usage

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

OpenAjax Conformance Requirement (Libraries): Verify Hub Version

Loading Requirements on the OpenAjax Hub

Only first version of the Hub must be loaded

Hub implementation mixing disallowed

What if different libraries include different versions of the Hub?

Reference implementation and test suite

Future versions and compatibility

Notational Conventions

Terminology

Views

Personal tools

Navigation

Search

Toolbox

Application loads a standalone version of `OpenAjax.js` before other Ajax libraries