OpenAjax Hub Specification v07 Libraries
(This wiki page holds a portion of the version 0.7 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.7 (September 3, 2007) draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v07. Version 0.7 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.
2 Library Management
Library Management Features
The OpenAjax Hub provides the following APIs for registering libraries, unregistering libraries, and querying about previously registered libraries:
This section lists conformance requirements that pertain to this chapter.
OpenAjax Conformance Requirement (Libraries): Library Registration
OpenAjax Conformance Requirement (Libraries): Read-only
To be OpenAjax Conformant, libraries MUST treat
OpenAjax.libraries as a read-only public variable.
OpenAjax.hub.registerLibrary(prefix, namespaceURI, version[, extraData])
Registers an Ajax library with the OpenAjax Hub.
- (Required) A unique string that identifies the library being registered. This string MUST be compatible with the prefix value within an xmlns attribute per the W3C's Namespaces in XML Recommendation, such as xmlns:foo="http://example.com".
- (Required) A namespace URI string suitable for use with xmlns attribute, such as xmlns:foo="http://example.com", where the namespace URI MUST be compatible with the W3C's Namespaces in XML Recommendation.
- (Required) 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.
- (Optional, and if provided, 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.
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.
Unregisters an Ajax library with the OpenAjax Hub.
- The unique string that identifies the library that was registered.
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).
This variable holds the list of libraries that have registered themselves with the OpenAjax Hub.
In order to achieve best execution time performance and smallest download size, OpenAjax Hub implementations MAY use
OpenAjax.hub.libraries to store its own internal information about registered libraries. Because of this, OpenAjax-conformant libraries MUST treat
OpenAjax.hub.libraries as a read-only variable and thus MUST NOT make any changes to this object or its contents.
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:
Developers should be aware that the content of
OpenAjax.hub.libraries is dynamic. It is possible, for example, that an Ajax library might unregister itself (and perhaps re-register itself) as the application runs. Therefore, applications SHOULD NOT retain persistent pointers to the internal contents of
OpenAjax.hub.libraries because those pointers might become out of sync with the current state of the Hub; instead, applications SHOULD access the internal values via a reference to
OpenAjax.hub.libraries each time before using those values.