OpenAjax Hub Specification v04 Introduction

From MemberWiki

Jump to: navigation, search

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

(This wiki page holds a portion of the version 0.4 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.4 draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_04. Version 0.4 is preserved for historical reasons and is very much out of date. A key point about version 0.4 is that it was the most recent version of the Hub spec before the March 2007 InteropFest.))

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


Contents

Introduction

First-generation Ajax interoperability shortcomings

First generation Ajax libraries often are designed with the assumption that developers will use these libraries in isolation from other Ajax libraries. First generation Ajax libraries thus often assume a "consequence-free" JavaScript environment where they are the first and last Ajax library to load within a given web page, not taking into account the possibility that other Ajax libraries might have executed before them (and thereby altered the state of the browser's JavaScript environment) or the possibility that other Ajax libraries might execute after them. As a result, it is problematic to build web pages that use multiple first-generation Ajax libraries together.

The OpenAjax Hub attempts to address these issues so that developers can integrate multiple Ajax technologies within the same Web application.

Use Cases

The overall use case for the OpenAjax Hub are the set of scenarios where an Ajax developer needs to deploy a single application that uses multiple Ajax libraries simultaneously. 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.

FIXME: Do we need more here?

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.

  1. Address the most important Ajax library interoperability issues
  2. Specifications and implementations MUST be royalty-free open technologies
  3. MUST be as lightweight as possible
  4. MUST require as few changes to existing Ajax libraries as possible
  5. MUST have an initial version available to the Ajax community on as fast a timescale as possible
  6. MUST allow existing toolkits to re-use existing syntax
  7. MUST allow the mixing/intermingling of widgets from different toolkits - multiple levels of mixed containment
  8. MUST optimize page scanning and widget creation
  9. MUST be simple from an end-user perspective
  10. MUST support both the Single-DOM and Dual-DOM approaches for Ajax toolkits.
  11. MUST include a robust, forward-looking approach to versioning for both the OpenAjax Hub and the Ajax libraries.
  12. MUST take into account the realities about limitations in today's browsers, such as poor XML namespace support in IE6.

Overview of features in OpenAjax Hub 1.0

The following are the major features that are included in OpenAjax Hub 1.0:

  1. Ajax library loading and unloading control - The Hub provides APIs for registering libraries, unregistering libraries, and querying about previously registered libraries.
  2. Techniques and tools to minimize JavaScript object collision - The Hub provides for managing the global objects that are added to the JavaScript runtime environment by Ajax libraries, thereby helping to minimize JavaScript objection collisions.
  3. Load and Unload Event Manager - The Hub provides APIs and mediates processing of 'load' and 'unload' event handlers on the <body> element to ensure that event handlers from different Ajax libraries do not collide with each other and are invoked at the appropriate time.
  4. 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.
  5. Markup scanner - The Hub provides APIs and logic to controls markup scanning and dispatching of particular elements for processing by particular libraries. At initialization time, Ajax libraries identify to the Hub the pattern matching criteria for the markup that the given library controls. When the Hub scans the document, whenever it encounters markup that matches the criteria, it invokes the library's appropriate callback function.

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.

There are different conformance requirements on different categories. For example, there is a set of conformance requirements on Ajax runtime libraries, a different set of conformance requirements on Ajax applications, and a different set of conformance requirements on Ajax IDEs.

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 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" language="JavaScript" type="text/javascript"></script>
[04]    <script src="scripts/foolib1.5/foo.js" language="JavaScript" type="text/javascript"></script>
[05]    <script src="scripts/barlib0.7/bar.js" language="JavaScript" type="text/javascript"></script>
[06]    <script src="scripts/myapp.js" language="JavaScript" 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.

FIXME: Need to point to an appendix with a complete example.

Application loads OpenAjaxBootstrap.js before other Ajax libraries

In this scenario, the application's HTML file loads a small bootstrap file for the OpenAJax Hub (in the example below, OpenAjaxBootstrap.js) 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/OpenAjaxBootstrap.js" language="JavaScript" type="text/javascript"></script>
[04]    <script src="scripts/foolib1.5/foo.js" language="JavaScript" type="text/javascript"></script>
[05]    <script src="scripts/barlib0.7/bar.js" language="JavaScript" type="text/javascript"></script>
[06]    <script src="scripts/myapp.js" language="JavaScript" type="text/javascript"></script>
[07]  </head>
[08]  <body>
[09]    <!-- Application-specific HTML markup goes here -->
[10]  </body>
[11]</html>

The above example is the same as the one in the previous section, except that only the OpenAjax bootstrap file is loaded directly. The bootstrap file will then auto-load the rest of the Hub via inserting <script> elements dynamically into the document that reference the other JavaScript files that make up the Hub.

One advantage of the bootstrapping approach is that it allows partial loading of the Hub, useful if your application only requires a subset of the Hub's functionality. For example, suppose your application does not require the Markup Scanner module of the Hub, but does require the Libraries, Globals, LoadUnload and PublishSubscribe modules. Then the <script> element for loading the Hub might look like this: 

...
    <script 
       src="scripts/openajax1.0/OpenAjaxBootstrap.js?load=Libraries,Globals,LoadUnload,PublishSubscribe"
       language="JavaScript" type="text/javascript"></script>
...

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:

  1. Make sure that the Ajax library that includes the OpenAjax Hub is loaded before the other Ajax libraries
  2. 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.registerLibrary(prefix,...); // Register library's prefix, namespaceURI, etc.
  OpenAjax.registerGlobals(prefix,...); // Register globals that library adds to JS environment
  OpenAjax.addOnLoad(...);              // Register callback for 'load' event
  OpenAjax.subscribe(prefix,...);       // Register callback for when particular events occur 
  OpenAjax.registerAttrScanCB(prefix,...); // Register a callback with Hub's Markup Scanner
} else {
  // The OpenAjax object does not exist, so don't use the Hub; instead,
  // perhaps the library registers its 'load' event handler directly with the browser
  // and invokes its own logic for any necessary markup scanning.
}

For more information about how libraries interact with the Hub, refer to OpenAjax Hub Specification Modularization and Inclusion.

Prefixes, Namespaces, Global Objects and Multiple Usage

The OpenAjax Hub assumes that each library defines its own unique prefix, namespace URI, and global objects that are designed to prevent collisions with other libraries and will not conflict with names that Web developers typically use as they develop applications.

The prefix holds a short name for the given library and MUST conform to W3C rules for namespace prefixes as defined in Namespaces in XML. 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. FIXME: 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).

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.

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.

NOTE: Related conformance criteria having to do with the OpenAjax Registry, prefixes, namespaces, and global objects can be found in the Globals Management chapter of this specification.

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

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.]OpenAjaxConfig
Configuration options that application developers can set to customize the behavior of the OpenAjax Hub.

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.

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 runtime characteristics necessary for particular scenarios, a different implementation of this specification definitely may be used, and 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.

FIXME: Add information about checking for errata and submitting suggestions and contributions to the specification, reference implementation, and test suite.

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 or OpenAjaxConfig objects. 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 either the OpenAjax or OpenAjaxConfig objects. The complete definition of those objects is controlled by future versions of the OpenAjax Hub Specification published by OpenAjax Alliance.

Implementations of the OpenAjax Hub may add private, implementation-specific methods and properties on either OpenAjax or OpenAjaxConfig 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.
markup processing (in the context of "Ajax markup processing")
The transformations performed by an Ajax library upon source markup to produce appropriate changes to the browser DOM to achieve the desired visual and behavioral results.
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.
Retrieved from "http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Introduction"
Personal tools