OpenAjax Hub 1.1 Specification Managed Hub Providers

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the early draft specification for OpenAjax Hub 1.1. It contains all of the finalized and approved content from the OpenAjax Hub 1.0 Specification, plus draft text for the new features in OpenAjax Hub 1.1. Text repeated from the Hub 1.0 spec isidentified by the string [HUB10]. The draft text for the features that are new to Hub 1.1 is identified by the string [HUB11]. At this point, the new features are very early in development and have received little or no review by the Interoperability Working Group. All of the new features should be treated by the community as a work in progress that is not yet ready for use by the community.

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


Contents

7 Managed Hub Providers

2009-01-04 NOTE: This chapter is likely to be changed radically soon. We have changed the architecture and nomenclature for Hub 1.1 and these changes need to be incorporated into this chapter. Our extensibility architecture is now based on JavaScript class hierarchies for "widget containers" instead of "communication providers" as implementation experience has shown us that the "inline" and "smash" modules were managing widget lifecycle and not just managing cross-widget communications.


[HUB11]: Everything in this chapter describes new features found in OpenAjax Hub 1.1.

NOTE: This chapter will contain an overview of the Managed Hub provider mechanism, discussion of the two built-in providers ("smash" and "inline"), and the SPI interfaces that allow for the development of other providers.


This chapter describes the SPI for the hub and communication service providers. The SPI allows different communication service providers to plug-in to OpenAjax.hub.

Communication Provider Registration and Configuration

OpenAjax.hubspi.register(providerObject:object)

This method is used by a provider to register itself with the hub.

Parameters

providerObject
An object representing the provider. It implements a set of methods including the following:
  • getProviderName() which returns the providerName string
  • getVersion() which returns the version of the provider using the same approach as the version parameter in OpenAjax.hub.registerLibrary of Hub 1.0.

[TBD] version represented as [0-9]+(\.[0-9]+)* [a-zA-Z0-9 .:;] with the second part ignored for version comparison. For two versions which have identical numbers in the first first position, the numerically higher one has to be backwards-compatible to the other one. [/TBD] [TBD] When registering a provider, are we going to allow multiple versions of a provider? If so, which one gets used when someone specifies the provider by name? The latest (by version number)? [/TBD]

Return value

The return value is a boolean indicating success or failure.

providerObject.configureProvider(providerConfig:object)

This method is used to give configuration parameters to the provider.

Parameters

providerConfig
The providerConfig is a data object to configure the provider.

Return value

The return value is a boolean that is true if the provider was configured, else false.


Additional methods implemented by a providerObject are described below.

Communication Provider SPI - at manager

A provider implements a different SPI for the two places it is used: (1) for plugging into the hub-instance on the manager side, (2) for allowing a client to connect to a hub-instance. Here we describe (1), and will describe (2) in the next section.

providerObject.isConnected(clientName:string)

Returns whether the given client is connected

Parameters

clientName
The name of the client

Return value

The return value is true if connected, else false.

providerObject.sendEvent(clientName:string, topic: string, data:JSON|string, matchingSubs:array of string)

Send an event to the given client.

Parameters

clientName
The name of the client
topic
The topic does not contain wildcards (see Hub 1.0 spec).
data
The event payload
matchingSubs
An array of matching subscription IDs

Communication Provider SPI - at client

At a client, a provider implements the connect method described below, and then all the method in the API for the connHandle object that it returns. Therefore, the provider behaves like a proxy to the hub-instance on the client-side.

providerObject.connect({[host:string], clientName:string, callback:function, [connectionConfig:object]})

This method connects a client to an existing hub-instance using this provider.

Parameters

The parameters are defined in the same manner as the OpenAjax.hub.connect method.

Return value

The return value is a connHandle object. It implements the same methods as described previously.

Hub SPI - at manager

OpenAjax.hubspi.registerClient(providerObject:object, clientName:string)

Called by a provider when a client uses it to connect to a hub-instance that is managed by this OpenAjax.hub object.

Parameters

providerObject
The providerObject corresponding to the provider used by the client
clientName
The name of the connecting client

OpenAjax.hubspi.publishEvent(pubClientName:string, topic:string, data:JSON|string)

Called by a provider when it receives an event from a client.

Parameters

pubClientName
The name of the client which published the event
topic
The topic does not contain wildcards (see Hub 1.0 spec).
data
The event payload

OpenAjax.hubspi.subscribeReq(subClientName:string, topic:string, subId:string)

Called by a provider when it receives a subscribe request from a client.

Parameters

subClientName
The name of the client which sent the subscribe request
topic
The topic can contain wildcards (see Hub 1.0 spec).
subId
The id of the subscription (unique relative to subClientName).

Return value

The return value is a boolean indicating success or failure. The return value is false if subCallback for this subscription returns false.

OpenAjax.hubspi.unsubscribeReq(subClientName:string, subId:string)

Called by a provider when it receives an unsubscribe request from a client.

Parameters

subClientName
The name of the client which sent the unsubscribe request
subId
The id of the subscription (unique relative to subClientName).

Return value

The return value is a boolean indicating success or failure.


Simple Scenario illustrating API and SPI calls

We illustrate the use of these API and SPI calls with a very simple scenario, a mashup application (MashupApp), containing two gadgets, GadgetA and GadgetB. GadgetA is an inline gadget and GadgetB is in an iframe sandbox. The gadgets have client names "GA" and "GB" respectively.

There are two OpenAjax.hub objects, which for convenience we will refer to as oah_maga and oah_gb. This represents the fact that the former OpenAjax.hub object is shared by MashupApp and GadgetA and the latter is only used by GadgetB (similarly we name oahspi_maga and oahspi_gb).

The oah_maga has two hub-instances, one for hub 1.0 style communication and the other for communication between MashupApp, GadgetA and GadgetB. We will only discuss the latter here, since our focus is on the new features of hub 1.1. For exposition purposes, we will refer to this hub-instance as ma-hub. The oah_gb has one hub-instance, for hub 1.0 style communication. We ill not discuss this hub-instance here.

There is one provider object for the inline communication provider, in the window shared by MashupApp and GadgetA, which we will refer to as inline_maga. There are two provider objects for the cross-frame communication provider (say based on SMash code), which we will refer to as smash_maga and smash_gb.

MashupApp actions

  • creation of ma-hub
    • oah_maga.createManagedHub(...)
      • returns a connHandle, say conn_ma.
  • loading of GadgetA (the following may be wrapped into a load call in the OpenAjax.gadget API)
    • conn_ma.bind({clientName:"GA"})
    • load GadgetA using some provider specific method
  • loading of GadgetB (the following may be wrapped into a load call in the OpenAjax.gadget API)
    • conn_ma.bind({clientID:"GB"})
    • load GadgetB using some provider specific method
  • publish, subscribe and unsubscribe using conn_ma

GadgetA actions

  • connection to ma-hub (may be done by OpenAjax.gadget bootstrapping code)
  • publish, subscribe and unsubscribe using conn_ga

GadgetB actions

  • connection to ma-hub (may be done by OpenAjax.gadget bootstrapping code)
  • publish, subscribe and unsubscribe using conn_gb

SPI calls

These are the SPI call patterns that will get executed in response to all the above actions.

  • inline_maga.sendEvent("GA", ...) : to send an event from the ma-hub to GadgetA.
  • smash_maga.sendEvent("GB", ...) : to send an event from the ma-hub to GadgetB.
  • oahspi_maga.publishEvent("GA"|"GB", ...) : when an event is received from GadgetA (by the inline provider) or GadgetB (by the SMash provider).
  • oahspi_maga.subscribeReq("GA"|"GB", ...) : when a subscribe request is received from GadgetA or GadgetB
  • oahspi_maga.unsubscribeReq("GA"|"GB", ...) : when an unsubscribe request is received from GadgetA or GadgetB
  • smash_gb.connect({clientName:"GB", ...})
    • The provider creates conn_gb and supports all the API methods on conn_gb.
  • inline_gagb.connect({clientName:"GA", ...})
    • The provider creates conn_ga and supports all the API methods on conn_ga.




<--previous       contents--^       next-->
Retrieved from "http://www.openajax.org/member/wiki/OpenAjax_Hub_1.1_Specification_Managed_Hub_Providers"
Personal tools