OpenAjax Hub 2.0 Specification Managed Hub APIs

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Hub 2.0 Specification.


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



Contents

6 Managed Hub APIs

Introduction

This chapter provides descriptions of the various APIs within the Managed Hub.

Some of the APIs defined within this chapter use JSDoc commenting conventions to describe various details about a particular API, such as a method's parameters, return values and exceptions. For details about the subset of JSDoc used in this specification, refer to the write-up on JSDoc Conventions in the Introduction chapter.

The following summarizes the classes, interfaces and singleton objects that comprise the Managed Hub APIs:


APIClass, Singleton, or Interface?Implements/ExtendsDescription
OpenAjax.hub.ErrorSingletonN/AProvides the list of error codes used by the various classes and interfaces that make up the Managed Hub
OpenAjax.hub.SecurityAlertSingletonN/AProvides the list of standard codes used when attempted security violations are detected
OpenAjax.hub.HubInterfaceN/AInterface that defines the APIs shared by OpenAjax.hub.ManagedHub and OpenAjax.hub.HubClient
OpenAjax.hub.ManagedHubClassImplements OpenAjax.hub.HubManager-side APIs to the Managed Hub
OpenAjax.hub.ContainerInterfaceN/ABase class for all containers. Subclasses include OpenAjax.hub.IframeContainer and OpenAjax.hub.InlineContainer
OpenAjax.hub.IframeContainerClassImplements OpenAjax.hub.ContainerThe container that is built into the OpenAjax Hub that provides component isolation, typically by placing each distinct component into its own Iframes whose (sub)domain differs from the main application and all other components.
OpenAjax.hub.InlineContainerClassImplements OpenAjax.hub.ContainerThe container that is built into the OpenAjax Hub that does not isolate components. Typically, components are inserted inline within an HTML DIV element inline within the main application's object tree.
OpenAjax.hub.HubClientInterfaceExtends OpenAjax.hub.HubClient-side (i.e., component-side) APIs to the Managed Hub
OpenAjax.hub.IframeHubClientClassImplements OpenAjax.hub. HubClient The IframeHubClient is the HubClient implementation that corresponds to the IframeContainer.
OpenAjax.hub.InlineHubClientClassImplements OpenAjax.hub. HubClient The InlineHubClient is the HubClient implementation that corresponds to the InlineContainer.

Within this chapter, the following terms have the following meanings:

  • A Class is a collection of related JavaScript logic that allows for object instantiation via the 'new' operator. For the APIs defined in this chapter, a class consists of:
    • A constructor function (e.g., function MyClass(...) {...}) whose name matches the name of the class (i.e., MyClass). An object instance of the class can be instantiated by using the 'new' operator. For example: var MyObject = new MyClass(...);.
    • Class methods defined on the class object prototype (e.g., MyClass.prototype.method1 = function(...) {...}).
  • An Interface refers to a related collection of APIs that an implementing class MUST implement.
  • A Singleton refers to a JavaScript object that provides APIs. As the name suggests, there is only one instance of a singleton.

OpenAjax.hub.Error

OpenAjax.hub.Error holds the list of errors thrown by the Managed Hub APIs.

OpenAjax.hub.Error = {
    // Either a required argument is missing or an invalid argument was provided
    BadParameters: "OpenAjax.hub.Error.BadParameters",
    // The specified hub has been disconnected and cannot perform the requested
    // operation:
    Disconnected: "OpenAjax.hub.Error.Disconnected",
    // Container with specified ID already exists:
    Duplicate: "OpenAjax.hub.Error.Duplicate",
    // The specified ManagedHub has no such Container (or it has been removed)
    NoContainer: "OpenAjax.hub.Error.NoContainer",
    // The specified ManagedHub or Container has no such subscription
    NoSubscription: "OpenAjax.hub.Error.NoSubscription",
    // Permission denied by manager's security policy
    NotAllowed: "OpenAjax.hub.Error.NotAllowed",
    // Wrong communications protocol identifier provided by Container or HubClient
    WrongProtocol: "OpenAjax.hub.Error.WrongProtocol"
};

OpenAjax.hub.SecurityAlert

OpenAjax.hub.SecurityAlert holds the list of standard codes used when attempted security violations are detected. Unlike Errors, these codes are not thrown as exceptions but rather passed into the SecurityAlertHandler function registered with the Hub instance.

OpenAjax.hub.SecurityAlert = {
    // Container did not load (possible frame phishing attack)
  LoadTimeout: "OpenAjax.hub.SecurityAlert.LoadTimeout",
    // Hub suspects a frame phishing attack against the specified container
  FramePhish: "OpenAjax.hub.SecurityAlert.FramePhish",
    // Hub detected a message forgery that purports to come to a specified container
  ForgedMsg: "OpenAjax.hub.SecurityAlert.ForgedMsg"
};

Common callback functions

OpenAjax.hub.onSecurityAlert callback function

Hub components use onSecurityAlert callback functions to notify application components when they have blocked serious attacks such as message forgery or frame phishing. While a security alert indicates that an attack has been prevented, applications SHOULD react quite forcefully when security alerts occur. See the "Best Practices" chapter for more details.

/**
 * onSecurityAlert callback for ManagedHub, Container and HubClient
 * Invoked within the scope defined by Hub.getScope(), when a security alert is raised.
 * Supplied to ManagedHub, Container and HubClient constructor via the onSecurityAlert parameter
 *
 * @param {Object} source  
 *     The Container or HubClient instance that raised the security alert
 * @param {OpenAjax.hub.SecurityAlert} alertType 
 *     The type of alert
 */
OpenAjax.hub.onSecurityAlert= function( source, alertType ) {}

The value of the source parameter is:

  • A Container instance, if a Container instance thwarts an attack
  • A HubClient instance, if a HubClient instance thwarts the attack

When an onSecurityAlert callback is invoked, the JavaScript this keyword refers to source.getScope().

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.log callback function

Logging helps developers to troubleshoot their applications. The constructors for ManagedHub, Container and HubClient allow the caller to specify optional logger callback functions. The implementation MAY use these logger functions to perform debug logging.

/**
 * The scope of the log function is the same as that of the object with which it is 
 * associated. If the log function is associated with a Container, then in the log
 * function, the JavaScript "this" keyword refers to the params.Container.scope 
 * that was passed into the Container constructor. 
 * 
 * @param {String} messageString The message to be logged
 */
OpenAjax.hub.log= function( messagestring ) {}

In most cases, logger callback functions simply call console.log. However, console.log is not fully portable, so other implementations may be needed in some environments.

Log messages:

  • are technical in nature
  • are unsuitable for end users
  • are not necessarily localized
  • contain content that is not defined by any standard and may differ from one implementation or version to another.

Thus, a log callback function SHOULD only be supplied during developer troubleshooting, and application code SHOULD NOT parse log messages and make decisions based on their contents.

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

If a particular log callback function is not provided, then the implementation SHOULD NOT generate the given log messages.

Host applications that use the Hub SHOULD code their log functions carefully to prevent cross-site scripting (XSS) attacks. In particular, host applications SHOULD avoid simple innerHTML assignments of the log messages to prevent malicious components from injecting executable content (e.g., a <script> element) through the logging mechanism.

OpenAjax.hub.onComplete callback function

Many Hub operations are asynchronous. For such operations, the only reliable way to determine when the operation completes, and whether it succeeds or fails, is to provide an onComplete callback function when invoking the operation.

/**
 * An onComplete callback function is invoked when an asynchronous API call,
 * such as HubClient.connect() or HubClient.subscribe(), completes.
 * When the callback is invoked, the JavaScript "this" keyword refers to the
 * object specified in the scope parameter of the asynchronous API call. 
 * 
 * @param {*} item
 *     Item on which the completed operation was invoked
 * @param {Boolean} success
 *     If operation succeeded (item is active) then true, else false
 * @param {OpenAjax.hub.Error} errCode
 *     If success != true, then contains a string error code, else is undefined
 */
onComplete = function(item, success, errCode) {}

Example parameter values for HubClient.subscribe:

// Example of success:
foo.onComplete(subscriptionID, true);
// Example of failure:
foo.onComplete(subscriptionID, false, "OpenAjax.hub.Error.NotAllowed");

When an onComplete callback function is invoked, the item parameter is either a HubClient or a subscription ID, depending on the operation with which the onComplete function is associated.

Notes about error codes:

  • The string error code is either one of the error codes listed in OpenAjax.hub.Error or a more specialized error code defined by the HubClient implementation.
  • HubClients SHOULD use the standard error codes rather than providing their own overlapping ones.
  • A HubClient implementation MAY define ADDITIONAL error codes for specialized situations that are only encountered in that particular implementation of HubClient.

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.Hub

The OpenAjax.hub.Hub interface is a base interface that is implemented on the manager side by OpenAjax.hub.ManagedHub. On the client side, OpenAjax.hub.HubClient extends OpenAjax.hub.Hub.

OpenAjax.hub.Hub.prototype.subscribe

subscribe creates a subscription on the specified topic name.

/**
 * Subscribe to a topic.
 *
 * @param {String} topic
 *     A valid topic string. MAY include wildcards.
 * @param {Function} onData   
 *     Callback function that is invoked whenever an event is 
 *     published on the topic
 * @param {Object} [scope]
 *     When onData callback or onComplete callback is invoked,
 *     the JavaScript "this" keyword refers to this scope object.
 *     If no scope is provided, default is window.
 * @param {Function} [onComplete]
 *     Invoked to tell the client application whether the 
 *     subscribe operation succeeded or failed. 
 * @param {*} [subscriberData]
 *     Client application provides this data, which is handed
 *     back to the client application in the subscriberData
 *     parameter of the onData callback function.
 * 
 * @returns subscriptionID
 *     Identifier representing the subscription. This identifier is an 
 *     arbitrary ID string that is unique within this Hub instance
 * @type {String}
 * 
 * @throws {OpenAjax.hub.Error.Disconnected} if this Hub instance is not in CONNECTED state
 * @throws {OpenAjax.hub.Error.BadParameters} if the topic is invalid (e.g. contains an empty token)
 */
OpenAjax.hub.Hub.prototype.subscribe = function( topic, onData, scope, onComplete, subscriberData ) {}

The subscribe function MUST immediately throw an exception if the topic is bad or if the Hub is not connected.

Otherwise, the operation continues. If an onComplete callback function has been provided, then, when the operation completes, the onComplete callback function is called. If the operation was successful, then the subscription is now "active," and the Hub can deliver published events by calling the onData callback function. On the other hand, if the subscribe operation failed, the subscription is now "inactive." The hub calls the onComplete callback function to report the error and then destroys the subscription.

In most Container implementations, subscribe operates asynchronously, so that the onComplete function typically is called after the subscribe function returns. In some implementations, however, subscribe operates synchronously, invoking onComplete before it returns. Applications that use this function SHOULD be programmed so that they can work with any Container (Iframe, Inline, or other). In order to handle the various possibilities, publishers and subscribers MUST follow certain practices, which are described in the "Publish Subscribe Best Practices" chapter.

If unsubscribe is called before the subscribe operation completes, then the Hub implementation MUST NOT invoke the onComplete callback for the subscribe operation if an unsubscribe operator has occurred before the subscribe operation has completed (e.g., due to a call to the hubClient.unsubscribe() method).

OpenAjax.hub.onData callback function

To deliver a published event to a subscriber, a Hub invokes the subscriber's onData callback function. When this callback is invoked, the JavaScript this keyword refers to the scope parameter that was supplied in the subscribe call. If no scope parameter was specified, then the default scope is window.

/**
 * onData callback functions
 * 
 * @param {String} topic  
 *     The topic on which the event was published
 * @param {*} data  
 *     The event "payload" data. Can be any JSON-serializable value. 
 * @param {*} subscriberData  
 *     The 'subscriberData' value that the caller supplied to the subscribe() call
 */
onData = function( topic, data, subscriberData ) {}

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.Hub.prototype.publish

This function publishes a data event on a topic.

/**
 * Publish an event on a topic
 *
 * @param {String} topic
 *     A valid topic string. MUST NOT include wildcards.
 * @param {*} data
 *     Valid publishable data. To be portable across different
 *     Container implementations, this value should be serializable
 *     as JSON.
 *     
 * @throws {OpenAjax.hub.Error.Disconnected} if this Hub instance is not in CONNECTED state
 * @throws {OpenAjax.hub.Error.BadParameters} if the topic cannot be published (e.g. contains 
 *     wildcards or empty tokens) or if the data cannot be published (e.g. cannot be serialized as JSON)
 */
OpenAjax.hub.Hub.prototype.publish = function( topic, data ) {}

The publish function immediately throws an exception if the topic or data cannot be published or if the Hub is not connected. Otherwise, the operation continues.

In most Container implementations, publish operates asynchronously, so that data is delivered to subscribers after the publish function returns. In some implementations, however, publish operates synchronously, delivering its data to the subscribers before returning. Applications that use this function SHOULD be programmed so that they can work with any Container (Iframe, Inline, or other). In order to handle the various possibilities, publishers and subscribers MUST follow certain practices, which are described in the "Publish Subscribe Best Practices" chapter.

When the implementation prevents a data item published by a client from being delivered to a subscriber, the publishing Client Application is NOT notified in any way. When a Client Application publishes, it cannot determine how many subscribers exist and it cannot determine how many of the existing subscribers received the published data item.

The data parameter is owned by the caller. The publish function does not modify it and the caller may continue to use it after publish() returns.

OpenAjax.hub.Hub.prototype.unsubscribe

Unsubscribe cancels an existing subscription.

/**
 * Unsubscribe from a subscription
 *
 * @param {String} subscriptionID
 *     A subscriptionID returned by Hub.subscribe()
 * @param {Function} [onComplete]
 *     Callback function invoked when unsubscribe completes
 * @param {Object} [scope]
 *     When onComplete callback function is invoked, the JavaScript "this"
 *     keyword refers to this scope object.
 *     If no scope is provided, default is window.
 *     
 * @throws {OpenAjax.hub.Error.Disconnected} if this Hub instance is not in CONNECTED state
 * @throws {OpenAjax.hub.Error.NoSubscription} if no such subscription is found
 */
OpenAjax.hub.Hub.prototype.unsubscribe = function( subscriptionID, onComplete, scope ) {}

The unsubscribe function immediately throws an exception if there is no subscription with the specified subscription ID. Otherwise, unsubscribe immediately deactivates the subscription. Once unsubscribe is called:

  • The onData and onComplete callback functions registered via subscribe will no longer be invoked.
  • Operations that require that the subscription be "active" throw OpenAjax.hub.Error.Disconnected.

When the unsubscribe operation completes, the onComplete function is invoked. In asynchronous implementations (e.g. OpenAjax.hub.IframeHubClient), this callback typically is invoked after the unsubscribe function returns. In synchronous implementations, such as ManagedHub and OpenAjax.hub.InlineClient, this callback typically is invoked before the unsubscribe function returns. See the "Publish Subscribe Best Practices" chapter for information about how to handle this range of behavior.

Note: Because unsubscribe immediately deactivates the subscription, whereas publish and subscribe might happen asychronously, in some implementations and/or on particular browsers the following sequence may result in the subscription being cancelled before the publishing event is completed:

function MyCallback(topic, data, subscriberData) {...}
var subscriptionID = hubClient.subscribe("org.example.topics.something", MyCallback);

// Because publishing to a subscriber can be asynchronous whereas unsubscribe
// operations are immediate, the subscription above might be cancelled by the 
// unsubscribe call below before the publish operation invokes the subscribe callback 
hubClient.publish("org.example.topics.something", somedata);  
hubClient.unsubscribe(subscriptionID);

OpenAjax.hub.Hub.prototype.isConnected

isConnected tells the caller whether the Hub is connected or not.

/**
 * Return true if this Hub instance is in the Connected state.
 * Else returns false.
 * 
 * This function can be called even if the Hub is not in a CONNECTED state.
 * 
 * @returns Boolean
 * @type {Boolean}
 */
OpenAjax.hub.Hub.prototype.isConnected = function() {}

This function MAY be called even when the Hub instance is not connected.

OpenAjax.hub.Hub.prototype.getScope

/**
 * Returns the scope associated with this Hub instance and which will be used
 * with callback functions.
 * 
 * This function can be called even if the Hub is not in a CONNECTED state.
 * 
 * @returns scope object
 * @type {Object}
 */
OpenAjax.hub.Hub.prototype.getScope = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Hub.prototype.getSubscriberData

This function returns the subscriberData associated with a subscription.

/**
 * Returns the subscriberData parameter that was provided when 
 * Hub.subscribe was called.
 *
 * @param {String} subscriberID
 *     The subscriberID of a subscription
 * 
 * @returns subscriberData
 * @type {*}
 * 
 * @throws {OpenAjax.hub.Error.Disconnected} if this Hub instance is not in CONNECTED state
 * @throws {OpenAjax.hub.Error.NoSubscription} if there is no such subscription
 */
OpenAjax.hub.Hub.prototype.getSubscriberData= function(subscriptionID) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Hub.prototype.getSubscriberScope

This function returns the scope object associated with a subscription.

/**
 * Returns the scope associated with a specified subscription.  This scope will
 * be used when invoking the 'onData' callback supplied to Hub.subscribe().
 *
 * @param {String} subscriberID
 *     The subscriberID of a subscription
 * 
 * @returns scope
 * @type {*}
 * 
 * @throws {OpenAjax.hub.Error.Disconnected} if this Hub instance is not in CONNECTED state
 * @throws {OpenAjax.hub.Error.NoSubscription} if there is no such subscription
 */
//OpenAjax.hub.Hub.prototype.getSubscriberScope = function(subscriberID) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Hub.prototype.getParameters

This function returns the params object associated with this Hub instance.

/**
 * Returns the params object associated with this Hub instance.
 *
 * @returns params
 *         The params object associated with this Hub instance
 * @type {Object}
 */
//OpenAjax.hub.Hub.prototype.getParameters = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.ManagedHub

The class OpenAjax.hub.ManagedHub implements OpenAjax.hub.Hub and provides manager-side APIs to the Managed Hub. Most ManagedHub functions are synchronous; in particular, functions that support onComplete callbacks invoke these callbacks before returning control to the caller.

OpenAjax.hub.ManagedHub constructor

/**
 * Create a new ManagedHub instance
 * @constructor
 *     
 * This constructor automatically sets the ManagedHub's state to
 * CONNECTED.
 * 
 * @param {Object} params
 *     Parameters used to instantiate the ManagedHub.
 *     Once the constructor is called, the params object belongs exclusively to
 *     the ManagedHub. The caller MUST not modify it.
 *     
 * The params object may contain the following properties:
 * 
 * @param {Function} params.onPublish
 *     Callback function that is invoked whenever a 
 *     data value published by a Container is about
 *     to be delivered to some (possibly the same) Container.
 *     This callback function implements a security policy;
 *     it returns true if the delivery of the data is
 *     permitted and false if permission is denied.
 * @param {Function} params.onSubscribe
 *     Called whenever a Container tries to subscribe
 *     on behalf of its client.
 *     This callback function implements a security policy;
 *     it returns true if the subscription is permitted 
 *     and false if permission is denied.
 * @param {Function} [params.onUnsubscribe]
 *     Called whenever a Container unsubscribes on behalf of its client. 
 *     Unlike the other callbacks, onUnsubscribe is intended only for 
 *     informative purposes, and is not used to implement a security
 *     policy.
 * @param {Object} [params.scope]
 *     Whenever one of the ManagedHub's callback functions is called,
 *     references to the JavaScript "this" keyword in the callback 
 *     function refer to this scope object
 *     If no scope is provided, default is window.
 * @param {Function} [params.log]  Optional logger function. Would
 *     be used to log to console.log or equivalent.
 * 
 * @throws {OpenAjax.hub.Error.BadParameters} if any of the required
 *     parameters are missing
 */
OpenAjax.hub.ManagedHub = function( params ) {}

A ManagedHub instance makes use of the params properties throughout its lifetime, and NOT just before the constructor returns. For example, the onPublish function will be invoked long after the constructor returns.

A ManagedHub is already in the connected state when the constructor returns.

OpenAjax.hub.ManagedHub onPublish callback function

An onPublish callback function defines a custom policy that controls which clients are allowed to send data on which topics to which clients. When creating a new ManagedHub, the Manager Application can specify an onPublish policy function.

/**
 * onPublish callback for ManagedHub
 * Invoked within the scope defined by ManagedHub.getScope(), when a
 * ManagedHub client publishes an event via publishForClient and the published
 * data is to be delivered to a second client
 * Supplied to ManagedHub constructor via the params.onPublish parameter
 *
 * @param {String} topic  
 *     The topic to which the first container is publishing
 * @param {*} data  
 *     The data that the first container is publishing
 * @param {OpenAjax.hub.Container} pcont  
 *     The container that is publishing (if the publisher is the Manager Application, pcont is null)
 * @param {OpenAjax.hub.Container} scont  
 *     The container to which the data is about to be delivered (if this is the Manager Application, 
 *     scont is null)
 * 
 * @returns true if the delivery of the data is allowed, else false
 * @type {boolean}
 */
OpenAjax.hub.onPublish = function( topic, data, pcont, scont ) {}

This function is invoked when the ManagedHub attempts to deliver a published event to one subcriber. Thus, if there are one publisher and 3 subscribers, onPublish will be called three times per event.

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

This function is invoked when EITHER ManagedHub.publishForClient or ManagedHub.publish is called.

When ManagedHub.publish is called, the pcont parameter of the onPublish callback is null. When the subscription belongs to the manager application rather than to a Container, the scont parameter of the onPublish callback is null.

OpenAjax.hub.ManagedHub onSubscribe callback function

An onSubscribe callback function defines a custom policy that controls which clients are allowed to subscribe to which topics. When creating a new ManagedHub, the Manager Application can specify an onSubscribe policy function.

/**
 * onSubscribe callback for ManagedHub
 * Invoked within the scope defined by ManagedHub.getScope(), when a
 * ManagedHub client subscribes via subscribeForClient.
 * Supplied to ManagedHub constructor via the params.onSubscribe parameter
 *
 * @param {String} topic  
 *    The topic to which the container is subscribing
 * @param {OpenAjax.hub.Container} container  
 *    The container that is subscribing
 * 
 * @returns true if the subscribe is allowed, else false
 * @type {boolean}
 */
OpenAjax.hub.onSubscribe = function( topic, container ) {}

When the onSubscribe callback function is called, the JavaScript this keyword is the object returned by ManagedHub.getScope().

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

This function is invoked when EITHER ManagedHub.subscribeForClient or ManagedHub.subscribe is called. When ManagedHub.subscribe is called, the container parameter of the onSubscribe callback is null.

OpenAjax.hub.ManagedHub onUnsubscribe callback function

An onUnsubscribe callback function alerts the Manager Application when a client unsubscribes from a topic.

/**
 * onUnsubscribe callback for ManagedHub
 * Invoked within the scope defined by ManagedHub.getScope(), when a
 * ManagedHub client unsubscribes via unsubscribeForClient.
 * Supplied to ManagedHub constructor via the params.onUnsubscribe parameter.
 *
 * @param {String} topic  
 *     The topic to which the container is unsubscribing
 * @param {OpenAjax.hub.Container} container  
 *    The container that is unsubscribing
 */
OpenAjax.hub.onUnsubscribe = function( topic, container ) {}

When the onUnsubscribe callback function is called, the JavaScript this keyword is the object returned by ManagedHub.getScope().

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

This function is invoked when EITHER ManagedHub.unsubscribeForClient or ManagedHub.unsubscribe is called.

When ManagedHub.unsubscribe is called, the container parameter of the onUnsubscribe callback is null.

OpenAjax.hub.ManagedHub.prototype.subscribeForClient

This function subscribes to a topic on behalf of a Container. It is typically called only by Container implementations.

/**
 * Subscribe to a topic on behalf of a Container. Called only by 
 * Container implementations, NOT by manager applications.
 * 
 * This function:
 * 1. Checks with the ManagedHub's onSubscribe security policy
 *    to determine whether this Container is allowed to subscribe 
 *    to this topic.
 * 2. If the subscribe operation is permitted, subscribes to the
 *    topic and returns the ManagedHub's subscription ID for this
 *    subscription. 
 * 3. If the subscribe operation is not permitted, throws
 *    OpenAjax.hub.Error.NotAllowed.
 * 
 * When data is published on the topic, the ManagedHub's 
 * onPublish security policy will be invoked to ensure that
 * this Container is permitted to receive the published data.
 * If the Container is allowed to receive the data, then the
 * Container's sendToClient function will be invoked.
 * 
 * When a Container needs to create a subscription on behalf of
 * its client, the Container MUST use this function to create
 * the subscription.
 * 
 * @param {OpenAjax.hub.Container} container  
 *     A Container
 * @param {String} topic 
 *     A valid topic
 * @param {String} containerSubID  
 *     Arbitrary string ID that the Container uses to 
 *     represent the subscription. Must be unique within the 
 *     context of the Container
 *
 * @returns managerSubID  
 *     Arbitrary string ID that this ManagedHub uses to 
 *     represent the subscription. Will be unique within the 
 *     context of this ManagedHub
 * @type {String}
 * 
 * @throws {OpenAjax.hub.Error.Disconnected} if this.isConnected() returns false
 * @throws {OpenAjax.hub.Error.NotAllowed} if subscription request is denied by the onSubscribe security policy
 * @throws {OpenAjax.hub.Error.BadParameters} if one of the parameters, e.g. the topic, is invalid
 */
OpenAjax.hub.ManagedHub.prototype.subscribeForClient = function( container, topic, containerSubID ) {}

If unsubscribeForClient is called before the subscribeForClient operation completes, then the implementation MUST NOT invoke the subscribeForClient function's onComplete callback.

OpenAjax.hub.ManagedHub.prototype.unsubscribeForClient

This function unsubscribes to a topic on behalf of a Container. It is typically called only by Container implementations.

/**
 * Unsubscribe from a subscription on behalf of a Container. Called only by 
 * Container implementations, NOT by manager application code.
 * 
 * This function:
 * 1. Destroys the specified subscription
 * 2. Calls the ManagedHub's onUnsubscribe callback function
 * 
 * This function can be called even if the ManagedHub is not in a CONNECTED state.
 * 
 * @param {OpenAjax.hub.Container} container  
 *    container instance that is unsubscribing
 * @param {String} managerSubID  
 *    opaque ID of a subscription, returned by previous call to subscribeForClient()
 * 
 * @throws {OpenAjax.hub.Error.NoSubscription} if subscriptionID does not refer to a valid subscription
 */
OpenAjax.hub.ManagedHub.prototype.unsubscribeForClient = function( container, managerSubID ) {}

Implementations are not required to verify that the specified subscription belongs to the specified Container.

OpenAjax.hub.ManagedHub.prototype.publishForClient

This function publishes a data event to a topic on behalf of a Container. It is typically called only by Container implementations.

/**
 * Publish data on a topic on behalf of a Container. Called only by 
 * Container implementations, NOT by manager application code.
 *
 * @param {OpenAjax.hub.Container} container
 *      Container on whose behalf data should be published
 * @param {String} topic
 *      Valid topic string. Must NOT contain wildcards.
 * @param {*} data
 *      Valid publishable data. To be portable across different
 *      Container implementations, this value SHOULD be serializable
 *      as JSON.
 * 
 * @throws {OpenAjax.hub.Error.Disconnected} if this.isConnected() returns false
 * @throws {OpenAjax.hub.Error.BadParameters} if one of the parameters, e.g. the topic, is invalid
 */
OpenAjax.hub.ManagedHub.prototype.publishForClient = function( container, topic, data ) {}

For each subscription that is "owned" by a Container, this function invokes the ManagedHub's onPublish security policy to determine whether to forward the data to the subscriber. If the onPublish policy callback returns true, then data is forwarded to the subscriber. Otherwise, the data is not forwarded to the subscriber (although no error is generated).

OpenAjax.hub.ManagedHub.prototype.disconnect

This function disables the ManagedHub and allows the garbage collector to clean it up.

/**
 * Destroy this ManagedHub
 * 
 * 1. Sets state to DISCONNECTED. All subsequent attempts to add containers,
 *  publish or subscribe will throw the Disconnected error. We will
 *  continue to allow "cleanup" operations such as removeContainer
 *  and unsubscribe, as well as read-only operations such as 
 *  isConnected
 * 2. Remove all Containers associated with this ManagedHub
 */
OpenAjax.hub.ManagedHub.prototype.disconnect = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.ManagedHub.prototype.getContainer

/**
 * Get a container belonging to this ManagedHub by its clientID, or null
 * if this ManagedHub has no such container
 * 
 * This function can be called even if the ManagedHub is not in a CONNECTED state.
 * 
 * @param {String} containerId
 *      Arbitrary string ID associated with the container
 *
 * @returns container associated with given ID
 * @type {OpenAjax.hub.Container}
 */
OpenAjax.hub.ManagedHub.prototype.getContainer = function( containerId ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.ManagedHub.prototype.listContainers

/**
 * Returns an array listing all containers belonging to this ManagedHub.
 * The order of the Containers in this array is arbitrary.
 * 
 * This function can be called even if the ManagedHub is not in a CONNECTED state.
 * 
 * @returns container array
 * @type {OpenAjax.hub.Container[]}
 */
OpenAjax.hub.ManagedHub.prototype.listContainers = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.ManagedHub.prototype.addContainer

/**
 * Add a container to this ManagedHub.
 *
 * This function should only be called by a Container constructor.
 * 
 * @param {OpenAjax.hub.Container} container
 *      A Container to be added to this ManagedHub
 * 
 * @throws {OpenAjax.hub.Error.Duplicate} if there is already a Container
 *      in this ManagedHub whose clientId is the same as that of container
 * @throws {OpenAjax.hub.Error.Disconnected} if this.isConnected() returns false
 */
OpenAjax.hub.ManagedHub.prototype.addContainer = function( container ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.ManagedHub.prototype.removeContainer

/**
 * Remove a container from this ManagedHub immediately
 * 
 * This function can be called even if the ManagedHub is not in a CONNECTED state.
 * 
 * @param {OpenAjax.hub.Container} container  
 *      A Container to be removed from this ManagedHub
 *  
 * @throws {OpenAjax.hub.Error.NoContainer}  if no such container is found
 */
OpenAjax.hub.ManagedHub.prototype. removeContainer = function( container ) {}

removeContainer does the following:

  1. Invoke Container.remove to shut down the Container
  2. Remove the Container from the Hub

OpenAjax.hub.Container

OpenAjax.hub.Container is an interface that MUST be implemented by all containers.

All versions of the OpenAjax Hub MUST implement two types of Containers:

  • OpenAjax.hub.IframeContainer
  • OpenAjax.hub.InlineContainer

These, and any custom containers that might be added to the OpenAjax Hub, are subclasses of OpenAjax.hub.Container.

OpenAjax.hub.Container constructor

/**
 * Container
 * @constructor
 * 
 * Container represents an instance of a manager-side object that contains and
 * communicates with a single client of the hub. The container might be an inline
 * container, an iframe FIM container, or an iframe PostMessage container, or
 * it might be an instance of some other implementation.
 *
 * @param {OpenAjax.hub.ManagedHub} hub
 *    Managed Hub instance
 * @param {String} clientID
 *    A string ID that identifies a particular client of a Managed Hub. Unique
 *    within the context of the ManagedHub.
 * @param {Object} params  
 *    Parameters used to instantiate the Container.
 *    Once the constructor is called, the params object belongs exclusively to
 *    the Container. The caller MUST not modify it.
 *    Implementations of Container may specify additional properties
 *    for the params object, besides those identified below.
 *    The following params properties MUST be supported by all Container 
 *    implementations:
 * @param {Function} params.Container.onSecurityAlert
 *    Called when an attempted security breach is thwarted.  Function is defined
 *    as follows:  function(container, securityAlert)
 * @param {Function} [params.Container.onConnect]
 *    Called when the client connects to the Managed Hub.  Function is defined
 *    as follows:  function(container)
 * @param {Function} [params.Container.onDisconnect]
 *    Called when the client disconnects from the Managed Hub.  Function is
 *    defined as follows:  function(container)
 * @param {Object} [params.Container.scope]
 *    Whenever one of the Container's callback functions is called, references
 *    to "this" in the callback will refer to the scope object. If no scope is
 *    provided, default is window.
 * @param {Function} [params.Container.log]
 *    Optional logger function. Would be used to log to console.log or
 *    equivalent. 
 *
 * @throws {OpenAjax.hub.Error.BadParameters}   if required params are not
 *   present or null
 * @throws {OpenAjax.hub.Error.Duplicate}   if a Container with this clientID
 *   already exists in the given Managed Hub
 * @throws {OpenAjax.hub.Error.Disconnected}   if ManagedHub is not connected
 */
OpenAjax.hub.Container = function( hub, clientID, params ) {}

A Container instance makes use of the params properties throughout its lifetime, and NOT just before the constructor returns. For example, the onSecurityAlert function is invoked whenever the Container instance prevents an attempted security breach, even if this happens long after the constructor returns.

Implementations of the OpenAjax Hub might need to add their own implementation-specific parameters. In order to avoid conflict with future versions of the OpenAjax Hub and other software that might extend the Hub, implementations SHOULD not store implementation-specific parameters directly on the Container object; instead, the recommended best practice is to place implementation-specific parameters on a sub-object (e.g., params.ABCOrg.*) where the sub-object's name (ABCOrg) is unlikely to collide with other implementations. One recommended technique to avoid collisions is for the name of the sub-object to reflect the name of the organization associated with the parameters on the sub-object.

OpenAjax.hub.Container onConnect callback function

/**
 * onConnect callback for Container
 * Invoked within the scope defined by params.Container.scope, when the specified
 * Container's client connects to the ManagedHub.
 * Supplied to Container constructor via the params.Container.onConnect parameter
 *
 * @param {OpenAjax.hub.Container} container  The Container that detected the connect
 */
OpenAjax.hub.ContainerCallbacks.onConnect = function( container ) {}

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.Container onDisconnect callback function

/**
 * onDisconnect callback for Container
 * Invoked within the scope defined by params.Container.scope, when the specified
 * Container's client disconnects from the ManagedHub.
 * Supplied to Container constructor via the params.Container.onDisconnect parameter
 *
 * @param {OpenAjax.hub.Container} container  The Container that detected the disconnect
 */
OpenAjax.hub.ContainerCallbacks.onDisconnect = function( container ) {}

This type of callback function SHOULD NOT throw exceptions. Conformant Hub implementations MUST catch all exceptions thrown by this type of callback, but may silently consume these exceptions.

OpenAjax.hub.Container.prototype.sendToClient

/**
 * Send a message to the client inside this container. This function MUST only
 * be called by ManagedHub. 
 * 
 * @param {String} topic
 *    The topic name for the published message
 * @param {*} data
 *    The payload. Can be any JSON-serializable value.
 * @param {String} containerSubscriptionId
 *    Container's ID for a subscription, from previous call to
 *    subscribeForClient()
 */
OpenAjax.hub.Container.prototype.sendToClient = function(topic, data, containerSubscriptionId) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Container.prototype.remove

/**
 * Shut down a container. remove does all of the following:
 * - disconnects container from HubClient
 * - unsubscribes from all of its existing subscriptions in the ManagedHub
 * 
 * This function is only called by ManagedHub.removeContainer
 * Calling this function does NOT cause the container's onDisconnect callback to
 * be invoked.
 */
OpenAjax.hub.Container.prototype.remove = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Container.prototype.isConnected

/**
 * Returns true if the given client is connected to the managed hub.
 * Else returns false.
 *
 * @returns true if the client is connected to the managed hub
 * @type boolean
 */
OpenAjax.hub.Container.prototype.isConnected = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Container.prototype.getClientID

/**
 * Returns the clientID passed in when this Container was instantiated.
 *
 * @returns The clientID
 * @type {String}  
 */
OpenAjax.hub.Container.prototype.getClientID = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Container.prototype.getPartnerOrigin

/**
 * If DISCONNECTED:
 * Returns null
 * If CONNECTED:
 * Returns the origin associated with the window containing the HubClient
 * associated with this Container instance. The origin has the format
 *  
 * [protocol]://[host]
 * 
 * where:
 * 
 * [protocol] is "http" or "https"
 * [host] is the hostname of the partner page.
 * 
 * @returns Partner's origin
 * @type {String}
 */
OpenAjax.hub.Container.prototype.getPartnerOrigin = function() {}

All of the leading web browsers prevent script running in a window from accessing the DOM/script of a window whose "origin" is different. This is an instance of the Same Origin Policy. Leading Web browsers prevent access if the two windows have different protocols or hosts.

Some browsers also prevent access if the two windows have different ports, but some do not. Others may allow large port numbers to wrap around in same origin checks.

In the interest of consistency, this function returns the "lowest common denominator" origin, i.e. "[protocol]://[host]". Two windows that have the same protocol and host but different ports will appear to share the same origin.

Example origins:

"http://www.openajax.org"
"https://mashexample.example.co.uk"

If the HubClient and Container are in the same window (InlineContainer) then the origin of the Container's partner is the origin of that window. If the client is in an iframe (IframeContainer) then the origin of the Container's partner is the origin of the iframe window.

OpenAjax.hub.Container.prototype.getParameters

This function returns the params object associated with this Container instance.

/**
 * Returns the params object associated with this Container instance.
 *
 * @returns params
 *    The params object associated with this Container instance
 * @type {Object}
 */
OpenAjax.hub.Container.prototype.getParameters = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.Container.prototype.getHub

This function returns the ManagedHub object associated with this Container instance.

/**
 * Returns the ManagedHub to which this Container belongs.
 *
 * @returns ManagedHub
 *         The ManagedHub object associated with this Container instance
 * @type {OpenAjax.hub.ManagedHub}
 */
OpenAjax.hub.Container.prototype.getHub = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.IframeContainer

OpenAjax.hub.IframeContainer implements the OpenAjax.hub.Container interface to provide a container that isolates client components into secure sandboxes by leveraging the isolation features provided by browser Iframes.

OpenAjax.hub.IframeContainer constructor

/**
 * Create a new Iframe Container.
 * @constructor
 * 
 * IframeContainer implements the Container interface to provide a container
 * that isolates client components into secure sandboxes by leveraging the
 * isolation features provided by browser iframes.
 * 
 * @param {OpenAjax.hub.ManagedHub} hub
 *    Managed Hub instance to which this Container belongs
 * @param {String} clientID
 *    A string ID that identifies a particular client of a Managed Hub. Unique
 *    within the context of the ManagedHub.
 * @param {Object} params  
 *    Parameters used to instantiate the IframeContainer.
 *    Once the constructor is called, the params object belongs exclusively to
 *    the IframeContainer. The caller MUST not modify it.
 *    The following are the pre-defined properties on params:
 * @param {Function} params.Container.onSecurityAlert
 *    Called when an attempted security breach is thwarted.  Function is defined
 *    as follows:  function(container, securityAlert)
 * @param {Function} [params.Container.onConnect]
 *    Called when the client connects to the Managed Hub.  Function is defined
 *    as follows:  function(container)
 * @param {Function} [params.Container.onDisconnect]
 *    Called when the client disconnects from the Managed Hub.  Function is
 *    defined as follows:  function(container)
 * @param {Object} [params.Container.scope]
 *    Whenever one of the Container's callback functions is called, references
 *    to "this" in the callback will refer to the scope object. If no scope is
 *    provided, default is window.
 * @param {Function} [params.Container.log]
 *    Optional logger function. Would be used to log to console.log or
 *    equivalent. 
 * @param {Object} params.IframeContainer.parent
 *    DOM element that is to be parent of iframe
 * @param {String} params.IframeContainer.uri
 *    Initial Iframe URI (Container will add parameters to this URI)
 * @param {String} params.IframeContainer.tunnelURI
 *    URI of the tunnel iframe. Must be from the same origin as the page which
 *    instantiates the IframeContainer.
 * @param {Object} [params.IframeContainer.iframeAttrs]
 *    Attributes to add to IFRAME DOM entity.  For example:
 *              { style: { width: "100%",
 *                         height: "100%" },
 *                className: "some_class" }
 * @param {Number} [params.IframeContainer.timeout]
 *    Load timeout in milliseconds.  If not specified, defaults to 15000.  If
 *    the client at params.IframeContainer.uri does not establish a connection
 *    with this container in the given time, the onSecurityAlert callback is
 *    called with a LoadTimeout error code.
 * @param {Function} [params.IframeContainer.seed]
 *    A function that returns a string that will be used to seed the
 *    pseudo-random number generator, which is used to create the security
 *    tokens.  An implementation of IframeContainer may choose to ignore this
 *    value.
 * @param {Number} [params.IframeContainer.tokenLength]
 *    Length of the security tokens used when transmitting messages.  If not
 *    specified, defaults to 6.  An implementation of IframeContainer may choose
 *    to ignore this value.
 *
 * @throws {OpenAjax.hub.Error.BadParameters}   if required params are not
 *          present or null
 * @throws {OpenAjax.hub.Error.Duplicate}   if a Container with this clientID
 *          already exists in the given Managed Hub
 * @throws {OpenAjax.hub.Error.Disconnected}   if hub is not connected
 */
OpenAjax.hub.IframeContainer = function( hub, clientID, params ) {}

The tunnel iframe mentioned above typically is a file that is included within an implementation of the Hub. The tunnel iframe usually is part of Hub's implementation of secure messaging.

An implementation of IframeContainer SHOULD detect when its iframe is navigated, as this is equivalent to a disconnect. As part of the detection system, the IframeHubClient inside the iframe window itself typically creates an iframe, which is called a tunnel iframe. The params.IframeContainer.tunnelURI parameter specifies the initial URL for the tunnel iframe in the same way that the params.IframeContainer.uri parameter specifies the initial URL of the container iframe. In both cases, these initial URLs are modified by the Hub, which adds tokens and FIM (fragment-identifier messaging) messages to the URLs.

The tunnel iframe URI MUST have the same origin as the Container iframe URI.

Some HubClient implementations may use a tunnel iframe for other things as well. For example, a HubClient might use the tunnel iframe to send messages back to the parent window via the tunnel's src URL.

OpenAjax.hub.IframeContainer.prototype.getIframe

/**
 * Get the iframe associated with this iframe container
 * 
 * This function returns the iframe associated with an IframeContainer,
 * allowing the Manager Application to change its size, styles, scrollbars, etc.
 * 
 * CAUTION: The iframe is owned exclusively by the IframeContainer. The Manager
 * Application MUST NOT destroy the iframe directly. Also, if the iframe is
 * hidden and disconnected, the Manager Application SHOULD NOT attempt to make
 * it visible. The Container SHOULD automatically hide the iframe when it is
 * disconnected; to make it visible would introduce security risks. 
 * 
 * @returns iframeElement
 * @type {Object}
 */
OpenAjax.hub.IframeContainer.getIframe = function( ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.InlineContainer

OpenAjax.hub.InlineContainer implements the OpenAjax.hub.Container interface to provide a container that places components inline within the same browser frame as the main mashup application. As such, this container does not isolates client components into secure sandboxes.

OpenAjax.hub.InlineContainer constructor

/**
 * Create a new Inline Container.
 * @constructor
 *
 * InlineContainer implements the Container interface to provide a container
 * that places components within the same browser frame as the main mashup
 * application. As such, this container does not isolate client components into
 * secure sandboxes.
 * 
 * @param {OpenAjax.hub.ManagedHub} hub
 *    Managed Hub instance to which this Container belongs
 * @param {String} clientID
 *    A string ID that identifies a particular client of a Managed Hub. Unique
 *    within the context of the ManagedHub.
 * @param {Object} params  
 *    Parameters used to instantiate the InlineContainer.
 *    Once the constructor is called, the params object belongs exclusively to
 *    the InlineContainer. The caller MUST not modify it.
 *    The following are the pre-defined properties on params:
 * @param {Function} params.Container.onSecurityAlert
 *    Called when an attempted security breach is thwarted.  Function is defined
 *    as follows:  function(container, securityAlert)
 * @param {Function} [params.Container.onConnect]
 *    Called when the client connects to the Managed Hub.  Function is defined
 *    as follows:  function(container)
 * @param {Function} [params.Container.onDisconnect]
 *    Called when the client disconnects from the Managed Hub.  Function is
 *    defined as follows:  function(container)
 * @param {Object} [params.Container.scope]
 *    Whenever one of the Container's callback functions is called, references
 *    to "this" in the callback will refer to the scope object. If no scope is
 *    provided, default is window.
 * @param {Function} [params.Container.log]
 *    Optional logger function. Would be used to log to console.log or
 *    equivalent. 
 *
 * @throws {OpenAjax.hub.Error.BadParameters}   if required params are not
 *    present or null
 * @throws {OpenAjax.hub.Error.Duplicate}   if a Container with this clientID
 *    already exists in the given Managed Hub
 * @throws {OpenAjax.hub.Error.Disconnected}   if ManagedHub is not connected
 */
OpenAjax.hub.InlineContainer = function( hub, clientID, params ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.HubClient

Interface OpenAjax.hub.HubClient extends OpenAjax.hub.Hub and provides client-side APIs (i.e., component-side APIs) to interact with the Managed Hub. Each HubClient implementation is specific to a particular implementation of OpenAjax.hub.Container.

OpenAjax.hub.HubClient constructor

/**
 * Create a new HubClient. All HubClient constructors MUST have this 
 * signature.
 * @constructor
 * 
 * @param {Object} params 
 *    Parameters used to instantiate the HubClient.
 *    Once the constructor is called, the params object belongs to the
 *    HubClient. The caller MUST not modify it.
 *    Implementations of HubClient may specify additional properties
 *    for the params object, besides those identified below. 
 * 
 * @param {Function} params.HubClient.onSecurityAlert
 *     Called when an attempted security breach is thwarted
 * @param {Object} [params.HubClient.scope]
 *     Whenever one of the HubClient's callback functions is called,
 *     references to "this" in the callback will refer to the scope object.
 *     If not provided, the default is window.
 * @param {Function} [params.HubClient.log]
 *     Optional logger function. Would be used to log to console.log or
 *     equivalent. 
 *     
 * @throws {OpenAjax.hub.Error.BadParameters} if any of the required
 *     parameters is missing, or if a parameter value is invalid in 
 *     some way.
 */
OpenAjax.hub.HubClient = function( params ) {}

A HubClient instance makes use of the params properties throughout its lifetime, and NOT just before the constructor returns. For example, the onSecurityAlert function is invoked whenever the HubClient instance prevents an attempted security breach, even if this happens long after the constructor returns.

Implementations MUST treat the params object as read-only and potentially changeable by the calling logic. Because the params object is read-only, implementations of the HubClient MUST not change the params object. Because the params object might be changed during the course of application execution, the implementation MUST store the values passed into the constructor in private variables.

Implementations of the OpenAjax Hub might need to add their own implementation-specific parameters. In order to avoid conflict with future versions of the OpenAjax Hub and other software that might extend the Hub, implementations SHOULD not store implementation-specific parameters on the HubClient object; instead, the recommended best practice is to place implementation-specific parameters on a subobject (e.g., params.ABCOrg.*) where the subobject's name (ABCOrg) is unlikely to collide with other implementations. One recommended technique to avoid collisions is to have the name of the subobject reflects the name of the company or product associated with the parameters on the subobject.

OpenAjax.hub.HubClient.prototype.connect

/**
 * Requests a connection to the ManagedHub, via the Container
 * associated with this HubClient.
 * 
 * If the Container accepts the connection request, the HubClient's 
 * state is set to CONNECTED and the HubClient invokes the 
 * onComplete callback function.
 * 
 * If the Container refuses the connection request, the HubClient
 * invokes the onComplete callback function with an error code. 
 * The error code might, for example, indicate that the Container 
 * is being destroyed.
 * 
 * In most implementations, this function operates asynchronously, 
 * so the onComplete callback function is the only reliable way to
 * determine when this function completes and whether it has succeeded
 * or failed.
 * 
 * A client application may call HubClient.disconnect and then call
 * HubClient.connect.
 * 
 * @param {Function} [onComplete]
 *     Callback function to call when this operation completes.
 * @param {Object} [scope]  
 *     When the onComplete function is invoked, the JavaScript "this"
 *     keyword refers to this scope object.
 *     If no scope is provided, default is window.
 *
 * @throws {OpenAjax.hub.Error.Duplicate} if the HubClient is already connected
 */
OpenAjax.hub.HubClient.prototype.connect = function( onComplete, scope ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.HubClient.prototype.disconnect

/**
 * Disconnect from the ManagedHub
 * 
 * Disconnect immediately:
 * 
 * 1. Sets the HubClient's state to DISCONNECTED.
 * 2. Causes the HubClient to send a Disconnect request to the 
 *      associated Container. 
 * 3. Ensures that the client application will receive no more
 *      onData or onComplete callbacks associated with this 
 *      connection, except for the disconnect function's own
 *      onComplete callback.
 * 4. Automatically destroys all of the HubClient's subscriptions.
 *
 * In most implementations, this function operates asynchronously, 
 * so the onComplete callback function is the only reliable way to
 * determine when this function completes and whether it has succeeded
 * or failed.
 * 
 * A client application is allowed to call HubClient.disconnect and 
 * then call HubClient.connect.
 * 	
 * @param {Function} [onComplete]
 *     Callback function to call when this operation completes.
 * @param {Object} [scope]  
 *     When the onComplete function is invoked, the JavaScript "this"
 *     keyword refers to the scope object.
 *     If no scope is provided, default is window.
 *
 * @throws {OpenAjax.hub.Error.Disconnected} if the HubClient is already
 *     disconnected
 */
OpenAjax.hub.HubClient.prototype.disconnect = function( onComplete, scope ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.HubClient.prototype.getPartnerOrigin

/**
 * If DISCONNECTED: Returns null
 * If CONNECTED: Returns the origin associated with the window containing the Container associated with this
 * HubClient instance. The origin has the format
 *  
 * [protocol]://[host]
 * 
 * where:
 * 
 * [protocol] is "http" or "https"
 * [host] is the hostname of the partner page.
 * 
 * @returns Partner's origin
 * @type {String}
 */
OpenAjax.hub.HubClient.prototype.getPartnerOrigin = function() {}

All of the major web browsers prevent script running in a window from accessing the DOM/script of a window whose "origin" is different. This is an instance of the Same Origin Policy. All of the major browsers prevent access if the two windows have different protocols or hosts.

Some major browsers also prevent access if the two windows have different ports, but some do not. Others may allow large port numbers to wrap around in same origin checks.

In the interest of consistency, this function returns the "lowest common denominator" origin, i.e. "[protocol]://[host]". Two windows that have the same protocol and host but different ports will appear to share the same origin.

Example origins:

"http://www.openajax.org"
"https://mashexample.example.co.uk"

If the HubClient and Container are in the same window (InlineHubClient) then the origin of the HubClient's partner is the origin of that window. If the client is in an iframe (IframeHubClient) then the origin of the HubClient's partner is the origin of the window associated with the ManagedHub that controls the Container.

OpenAjax.hub.HubClient.prototype.getClientID

/**
 * Returns the client ID of this HubClient
 *
 * @returns clientID
 * @type {String}
 */
OpenAjax.hub.HubClient.prototype.getClientID = function() {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.IframeHubClient

Class OpenAjax.hub.IframeHubClient implements OpenAjax.hub.HubClient for an IframeContainer and provides client-side APIs (i.e., component-side APIs) to interact with the Managed Hub..

OpenAjax.hub.IframeHubClient constructor

/**
 * Create a new IframeHubClient.
 * @constructor
 * 
 * @param {Object} params
 *    Once the constructor is called, the params object belongs to the
 *    HubClient. The caller MUST not modify it.
 *    The following are the pre-defined properties on params:
 * @param {Function} params.HubClient.onSecurityAlert
 *     Called when an attempted security breach is thwarted
 * @param {Object} [params.HubClient.scope]
 *     Whenever one of the HubClient's callback functions is called,
 *     references to "this" in the callback will refer to the scope object.
 *     If not provided, the default is window.
 * @param {Function} [params.HubClient.log]
 *     Optional logger function. Would be used to log to console.log or
 *     equivalent. 
 * @param {Function} [params.IframeHubClient.seed]
 *     A function that returns a string that will be used to seed the
 *     pseudo-random number generator, which is used to create the security
 *     tokens.  An implementation of IframeHubClient may choose to ignore
 *     this value.
 * @param {Number} [params.IframeHubClient.tokenLength]
 *     Length of the security tokens used when transmitting messages.  If
 *     not specified, defaults to 6.  An implementation of IframeHubClient
 *     may choose to ignore this value.
 *     
 * @throws {OpenAjax.hub.Error.BadParameters} if any of the required
 *          parameters is missing, or if a parameter value is invalid in 
 *          some way.
 */
OpenAjax.hub.IframeHubClient = function( params ) {}

The JSDoc comments above fully describe this API.

OpenAjax.hub.InlineHubClient

Class OpenAjax.hub.InlineHubClient implements OpenAjax.hub.HubClient for an InlineContainer and provides client-side APIs (i.e., component-side APIs) to interact with the Managed Hub.

The following functions of InlineHubClient typically are SYNCHRONOUS:

  • connect
  • disconnect
  • subscribe
  • unsubscribe

This means that for all of these functions, the associated onComplete callbacks - and any other callbacks, e.g. Container.onSubscribe - typically are invoked BEFORE these functions return. Developers are cautioned that in most implementations of HubClient, onComplete is invoked after this function returns.

In addition, InlineHubClient.publish typically is SYNCHRONOUS. This means that the Container's onPublish and the publish function's onData callbacks typically are invoked before the publish call returns. Developers are cautioned that in most implementations of HubClient, onData is invoked after this function returns.

OpenAjax.hub.InlineHubClient constructor

/**
 * Create a new InlineHubClient.
 * @constructor
 * 
 * @param {Object} params 
 *    Parameters used to instantiate the HubClient.
 *    Once the constructor is called, the params object belongs to the
 *    HubClient. The caller MUST not modify it.
 *    The following are the pre-defined properties on params:
 * @param {Function} params.HubClient.onSecurityAlert
 *     Called when an attempted security breach is thwarted
 * @param {Object} [params.HubClient.scope]
 *     Whenever one of the HubClient's callback functions is called,
 *     references to "this" in the callback will refer to the scope object.
 *     If not provided, the default is window.
 * @param {Function} [params.HubClient.log]
 *     Optional logger function. Would be used to log to console.log or
 *     equivalent. 
 * @param {OpenAjax.hub.InlineContainer} params.InlineHubClient.container
 *     Specifies the InlineContainer to which this HubClient will connect
 *  
 * @throws {OpenAjax.hub.Error.BadParameters} if any of the required
 *     parameters are missing
 */
OpenAjax.hub.InlineHubClient= function( params ) {}

The JSDoc comments above fully describe this API.


<--previous       contents--^       next-->
Personal tools