OpenAjax Hub 1.0 Specification Libraries
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", followed by an optional arbitrary string (e.g., "1.20.2Beta" or "1.1 Build 543"). The leading numeric part of the version string allows script to determine which version of a particular Ajax library has been loaded, using equal/greater-than/less-than comparisons. The optional trailing arbitrary string must begin with a character other than a numeric character (i.e., 0-9) or period character. The optional trailing string must be stripped before invoking version comparison logic.
The first (non-negative) integer token of the leading numeric part SHOULD reflect the library's major release number. If present, the second (non-negative) integer token of the leading numeric part SHOULD reflect the minor release number. If present, the third (non-negative) integer token of the leading numeric part SHOULD reflect the (next level down) minor release ("minor-minor" release number). It is acceptable to include other numeric values (4th, 5th, etc.) although probably not useful. To illustrate, with the value "1.20.3 beta 7", the major release is "1", the minor release is "20", and the minor-minor release is "3".
In version comparison logic, first extract out the leading numeric part of the version string; then tokenize the numeric part. First do a numeric comparison of major version tokens. If equal, then compare minor versions. If equal, then compare minor-minor versions. Etc. Missing tokens are equivalent to zero.
Subsequent releases of a given toolkit MUST have version numbers that are greater than or equal to previous releases. Although not required, it is recommended that each release have a higher version number than previous releases. One technique to accomplish this is use the build number for the 3rd token (the "minor-minor" release number), such as "1.3.2065", where the major version is "1", the minor version is "3", and the build number is "2065".
- (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.