OpenAjax Hub Specification v05 Libraries
From MemberWiki
(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.5 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.5 draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v05. Version 0.5 is preserved for historical reasons and therefore may be out of date. A key point about version 0.5 is that it holds the first stable version after implementing decisions about the Hub made at the March 2007 face-to-face meeting and in the follow-in meetings which resolved detailed issues from March to May 2007.)
Contents |
Library Management
Library Management Features
The OpenAjax Hub provides the following APIs for registering libraries, unregistering libraries, and querying about previously registered libraries:
- OpenAjax.hub.registerLibrary()
- OpenAjax.hub.unregisterLibrary()
Conformance Requirements
OpenAjax Conformance Requirement (Libraries): Library Registration
To be OpenAjax Conformant, libraries MUST register themselves properly via OpenAjax.registerLibrary() at the time when the <script> tag(s) that includes the given library is processed (i.e., when the JavaScript files are fetched and then parsed by the browser's JavaScript's engine).
OpenAjax Conformance Requirement (Libraries): Read-only OpenAjax.libraries
To be OpenAjax Conformant, libraries MUST treat OpenAjax.libraries as a read-only public variable.
APIs
OpenAjax.hub.registerLibrary(prefix, namespaceURI, version[, extraData])
Registers an Ajax library with the OpenAjax Hub.
Parameters
- prefix
- A unique string that identifies the library being registered. This string should be suitable as the prefix within an xmlns attribute, such as xmlns:foo="http://example.com".
- namespaceURI
- A namespace URI string suitable for use with xmlns attribute, such as xmlns:foo="http://example.com".
- version
- Version number in the form of #[.#]*, such as "1", "1.1" or "1.20.2". This value allows script to determine which version of a particular Ajax library has been loaded, using equal/greater-than/less-than comparisons. The first (whole number) value should reflect the library's major release number. The second value should reflect the "dot release" number. The third value is for minor bug fixes releases. It is acceptable to include other values (4th, 5th, etc.) although probably not useful.
- extraData
- Optional, can be null. An arbitrary Object holding extra information about the library. This field might be used to hold build or release numbers or indicate alpha/beta status.
Return value
None.
Notes
It is not an error to re-register a library. If OpenAjax.hub.registerLibrary is called on a library that is already registered, then the new registration must replace the previous registration.
Immediately after the library has been registered (or re-registered), the Hub implementation must invoke OpenAjax.hub.publish(), where the event name is org.openajax.hub.registerLibrary and publisherData is a reference to the OpenAjax.hub.libraries[prefix] object for the given library.
OpenAjax.hub.unregisterLibrary(prefix)
Unregisters an Ajax library with the OpenAjax Hub.
Parameters
- prefix
- The unique string that identifies the library that was registered.
Return value
None.
Notes
It is not an error to unregister a library that is not currently registered. If OpenAjax.hub.unregisterLibrary is called on a library which is not currently registered, then the unregister request must result in no action and must not generate an exception.
Immediately before the Hub implementation attempts to unregister the given library, even if the specified library is not currently registered, the Hub implementation must invoke OpenAjax.hub.publish(), where the event name is org.openajax.hub.unregisterLibrary and publisherData is a reference to the OpenAjax.hub.libraries[prefix] object for the given library (or null if the given library is not currently registered).
Public variables
OpenAjax.hub.libraries
This variable holds the list of libraries that have registered themselves with the OpenAjax Hub. OpenAjax-conformant libraries must treat this as a read-only variable.
OpenAjax.hub.libraries is a JavaScript associative array, where OpenAjax.hub.libraries contains a <prefix> property for each library that has registered itself via OpenAjax.hub.registerLibrary(). For example, if the FooLib library has prefix foo and has registered itself via OpenAjax.hub.registerLibrary(), then there will be a OpenAjax.hub.libraries.foo property. The OpenAjax.hub.libraries.foo property must point to an object that in turn will have four properties, 'prefix', 'namespaceURI', 'version', and 'extraData', which will hold the corresponding values that were passed to OpenAjax.hub.registerLibrary(). Therefore, the 'version' for FooLib can be found at: OpenAjax.hub.libraries.foo.version
(Note: if parameter 'extraData' was not passed to OpenAjax.hub.registerLibrary(), then the Hub implementation must set the 'extraData' property on OpenAjax.hub.libraries.foo to null.)
