OpenAjax Hub Specification v07 Libraries

From MemberWiki

Jump to: navigation, search

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


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


Contents

2 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

This section lists conformance requirements that pertain to this chapter.

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
(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".
namespaceURI
(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.
version
(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.
extraData
(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.

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.

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

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.

Personal tools