View source

List of tasks (or issues) necessary to finish the OpenAjax Hub 1.1 API (in no particular order):

= Open items =


<span style="color:green; font-size:150%">'''''NOTE: Latest Hub 1.1 API proposals are here:'''''</span>
* <span style="font-size:150%">[[Hub 1.1 Proposal Nov 2008]]</span>


== Recent email (leading up to 15Dec08) ==
===Howard/Javier email thread on APIs===
====Discussion items from this thread====

===== getParameters =====
What is the point of the 2 getParameters() functions?  I can't think of 
a good use case where these would be useful.
* Howard: points out two scenarios where parameters might be used: (a) containers should be able to use ManagedHub's onSecurityAlert callback, (b) containers should be able to use their MH's scope parameter on onConnect, onDisconnect, and the MH's onSecurityAlert callbacks.
* Javier: OK, sounds fine, but need some best practices
* Howard: BPs for both container developers and application developers (both managers and clients)
* Jon (here): are parameters only on the manager side and hold implementation-private information?
* <span style="color:red">'''DISCUSSED 2008-12-08: ''' No resolution. Need to talk to Howard. Javier and Jon thought this only made sense on manager side, but is on the base class.'''</span>
* <span style="color:red">'''EMAIL AFTER 2008-12-08: ''' Howard points out that HubClient constructor takes a 'params' value, so getParameters() allows retrieval of that value. Jon is satisfied with getParameters on OpenAjax.hub.Hub. Probably can close this one.'''</span>
* <span style="color:red">'''DISCUSSION 2008-12-15: ''' Javier wonders if Howard's examples for getParameters might be hokey and requests that we leave this open to allow his to think about it some more.'''</span>

==States==
* Howard said something at F2F about Hub having a cleanly defined notion of application state or widget state
* Howard, do you remember what this was about?
<span style="color:blue">'''Discussed on 2008-11-13. Left open pending detailed proposal. We need to clearly define a finite state machine for widget lifecycle to cover case of connect();connect(); and things like that. On both client and server. '''</span>

== Split the 'old' (version 1.0) and 'new' (version 1.1) APIs into separate entities ==
*This allows a developer who only needs the older APIs to include a small file, whereas if they want the expanded APIs, they would include both files.
** Need to define a proper SPI for interaction between the 1.1 and 1.0 code bases.  That way, the 1.1 code could make use of the subscription tree algorithm in the 1.0 code.
*<span style="color:red">'''DISCUSSED 2008-12-08:''' Discussed on the telecon and confirmed by Howard via email: Yes, we want this, but let's look into the detailed strategies for this after we get the changed APIs working.</span>

== Error handling ==
* No error bubbling
* Spec needs to standardize the error conditions

== Unit tests ==
* Security tests

== Make 1.1 version of publish() take an Object as a payload, instead of a String (to match 1.0 version) ==
* Leave it up to the provider to deal with the Object
** i.e. The 'inline' provider would simply use the Object as-is
** i.e. The 'smash' provider would use a JSON string interpretation of the Object
*** If the object has a toJSON() method, use that.  Otherwise, call JSON.stringify().
*** How best to parse the JSON string on the other end: it would be best to use the object's fromJSON() method, if it exists; but first we would need to know which object type it is

== Standardized/shareable event names ==
* Are there 5-10 commonly used topics we can standardize?
* Create self-service topic registry
* Extend widget format to allow definition of payloads - Need to raise an ISSUE

== Code reviews ==
Review timeout logic to make sure it is suitable for commercial product deployment
* Review Hub 1.1 feature set against requirements of existing industry mashup products
* Reconciliation with Google Gadgets 0.8 rpc
** Emulate rpcin future version of OpenAjaxHub?
** How to package Hub 1.1

== Documentation and samples ==
* Explanation of how to write a widget
* Explanation of how to write a provider
* Explanation to mashup tools of how to develop an effective security manager

= Closed items =

==Providers==
* What we have now: inline, smash/FIM
* What we definitely need: postMessage
* What we might need: window.name
** For IE to prevent clicking sound
** But Google Gadgets might have alternate approach to prevent clicking
** And we have to make sure we can implement this protocol in a secure and performant manner
* Javier and Jon think we should drop plug-in provider approach, at least from this release. 
** Adds too much complexity. For example, here is the sort of thing we would need to address:
*** Properly define APIs for configuring the provider in a generic fashion
**** i.e. should not have to call smash.prepareForLoad()
** Other communication techniques need to share larger portions of "SMash" (FIM) provider logic anyway
** Gadgets has a pseudo class hierarchy approach that addresses extensibility requirement
<span style="color:blue">'''Discussed on 2008-11-13. Left open pending a detailed proposal.'''</span>
* <span style="color:blue">'''Agreement to see if we can get around clicking on IE without window.name.'''</span>
* <span style="color:blue">'''Concern window.name cannot be made secure.'''</span>
* <span style="color:blue">'''OK to replace plugin provider approach with a subclassing approach like what Gadgets is doing. Action on Jon/Javier to submit a concrete proposal for next phone call.'''</span>
<span style="color:green">'''First draft of new proposal availabe here: [[Hub 1.1 Proposal Nov 2008]]'''</span>
* <span style="color:blue">'''CLOSED 2008-12-08: ''' Had been left open pending a detailed proposal. We now have a detailed proposal, so OK to close.</span>

==Add the 'scope' parameter to the 1.1 version of the subscribe() method -- to match 1.0 API.==
* Any others from 1.0? (i.e. 'subscriberData', 'filter') - Raise this as an ISSUE
<span style="color:blue">'''RESOLUTION 2008-11-13:'''</span>
* <span style="color:blue">'''Add 'scope' parameter to connHandle.subscribe(), but don't add filter or subscriberData'''</span>
* <span style="color:blue">'''Put note in Hub 1.0 API section to say that filter and subscriberData are deprecated'''</span>
* <span style="color:blue">'''Add text in spec to talk about how to achieve filters and subscriberData using other techniques'''</span>

==PMEs: Properties/methods/events==
* Google Gadgets supports all three
** Events: pubsub similar to what we have
** Methods: They have an RPC mechanism
*** There are named interfaces (aka features) that some widgets provide and other widgets invoke.  
*** Container links providers with invokers
*** To invoke, issue an gadgets.rpc.call(...,callback) function
** Properties
*** Via Gadgets preferences
*** We put properties at a higher level (within metadata spec)
*** Gadgets is monolithic so they don't separate runtime versus container
* Do we need all 3 also? (Probably not for 1.1, but let's discuss)
<span style="color:blue">'''RESOLUTION 2008-11-13: Don't pursue Hub-level properties or methods with Hub 1.1 - too complex, not absolutely needed, lots of issues. Remote method invocation (2-way pub/sub) is something to consider for a subsequent version.'''</span>

== Latecomer widgets missing earlier events ==
* Could be addressed via properties, where we tell developers that if their message might be of interest to latecomers, then define the event via the &lt;property topic="whatever" publish="true"&gt; element
<span style="color:blue">'''RESOLUTION 2008-11-13: Don't pursue anything in Hub for Hub 1.1. Must be solved at application level. Should talk about this issue and candidate techniques in primers or tutorials.'''</span>

== Recent email (leading up to 08Dec08) ==
===Howard/Javier email thread on APIs===
* Javier: http://openajax.org/pipermail/interop/2008q4/000694.html
* Howard: http://openajax.org/pipermail/interop/2008q4/000696.html
* Javier: http://openajax.org/pipermail/interop/2008q4/000699.html
* Howard: http://openajax.org/pipermail/interop/2008q4/000700.html
* Javier: http://openajax.org/pipermail/interop/2008q4/000695.html

===== subscriberData =====
I thought we decided to get rid of 'subscriberData' for subscribe()?  Do 
you now think it would be good to keep this around?
* Javier/Howard: let's keep subscriberData
* Jon (here): +1
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Keep subscriberData.</span>

===== unsubscribe onDone callback =====
For OpenAjax.hub.Hub.prototype.unsubscribe(), does the user just assume 
that the operation succeeded (like publish()), or should we have an 
onComplete() callback?  I'm not sure if a callback would get us much here, 
but just wanted to bring this up, as the old APIs had such a callback.
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Add onDone</span> <span style="color:red">''Actually, onComplete instead of onDone''</span>

===== sendEvent subscriptionId parameter=====
In the code I just checked in, I have the sendEvent() function taking a 
3rd parameter: the subscription id.  My reasoning is that if the function 
only takes 'topic' and 'data', then the container must have its own mini 
subscription tree (or at least an associative array).  But it must also 
keep a mapping between the subscription handle and relevant data.  But if 
sendEvent() takes 'topic', 'data' and the subscription ID, it makes things 
easier.
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Add subscriptionId</span>

===== subscribe/publish callbacks =====
If a subscribe() is disallowed by the onSubscribe callback, then 
subscribeForClient() should return false; true otherwise.  The same cannot 
be done for the onPublish callback, since the publish events don't give 
feedback.
* Howard broke down the various cases in an email (MH vs client, iframe vs inline, etc.)
* Javier/Howard seem to agree that we need a NotAllowed error code.
* Regarding multiple error callbacks versus single error callback, Javier says "I am all for having a single onError function". Howard proposes 'onSecurityAlertError' vs. 'onWarning'. (Jon prefers multiple)
* Tangent discussion about whether clients should be notified of permission denied. Howard says "Right now I am treating authorization failures as warnings." (Jon thinks it's OK to tell the client if authorization fails but without any details and wonders if we can have the same set of callbacks for multiple scenarios)
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' OK with Howard's breakdown. Will add NotAllowed. Separate security callback from other error callbacks. Will tell client if permission denied, but one simple permission denied message without any details.</span>
* Details on Howard's proposal:
<pre>
(e) in more detail, the functionality at the hub level is as
follows: 
 
    When onSubscribe denies a client's permission to subscribe
    to a topic, the Container communicates the rejection to the
    HubClient. The HubClient notifies the client application
    via the onComplete callback, specifying the error
    (OpenAjax.hub.Error.NotAllowed) and identifying the
    HubClient subscription handle associated with the
    rejection.

    When onPublish prevents a data item published by a client
    from being delivered to a subscriber, THE PUBLISHING
    CONTAINER IS NEVER NOTIFIED. When a client publishes, it
    cannot tell how many subscribers exist, and it cannot tell
    how many of the existing subscribers received the published
    data item.
</pre>

===== Distinguishing between multiple managed Hubs =====

<pre>
> 
> In the JSDoc for _sendToClient(), you state that the onPublish() callback
> takes 'null' for the publisher ID if the publisher is a ManagedHub.  However,
> if the user has two or more managed hubs and uses the same onPublish()
> callback, they would not be able to differentiate between the multiple managed
> hubs.  Of course, this is probably a pretty rare use case, so we probably
> don't need to consider it too much.  Just wanted to throw it out there.

The following options are available to us:

1. Tell the programmer to use different scope objects
    (which can be specified in the ManagedHub constructor
    params) to differentiate, or to just use different callbacks.
2. Add a mhub parameter to onPublish and onSubscribe.
3. Add a mandatory hub ID or hub name argument to onPublish/onSubscribe.
    Add a mandatory hub name parameter to ManagedHub(params)
    that the manager must specify when creating a ManagedHub.
    Add a function to get a hub's id. Don't allow duplicate IDs.
    Variations on this theme are possible but are pointless.
4. Make each ManagedHub be a kind of crippled default Container,
    presumably without implementing operations like sendEvent,
    getParameters, etc. Add an operation to all Containers that
    allows the caller to check whether this is just a ManagedHub
    or a real Container, or force the clientID to have a special
    syntax if this is a ManagedHub.
5. Make each ManagedHub CREATE a private special Container to
    use for this kind of thing.

1 works today, and since we agree that the scenario you mentioned will
happen quite infrequently, and that the developer has complete control over
whether it happens or not, I would be happy to leave this as is.

2 would be trivial. I would be fine with doing this.

3 is awkward, and there is no point. If this is necessary, do 2 instead.

4 is extremely awkward. I definitely want to avoid doing this.

5 ties a specific Container implementation into the base ManagedHub
implementation. I definitely want to avoid doing this.
</pre>

Howards says his first choice is #1, then #2. and none of the other choices make sense. Javier and Jon agree with #1.

* <span style="color:blue">'''RESOLUTION 2008-12-15: Go with #1 (which means no spec changes).'''</span>

===== JSDoc any =====
I also have some minor edits to the API wiki (still to be done), mainly to 
the descriptions.  Also, JSDoc question: how do you represent a type that 
can be anything?  I've been using "*", but I'm not sure that's right...
* Jon (here): "*" is good
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Use "*"</span>

=== Property naming conventions within reference implementation ===
* Howard: ttp://openajax.org/pipermail/interop/2008q4/000701.html
(use camelcase for public things, use leading underscore for implementation-private things)
* Jon (here): +1
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Adopt Howard's proposal. (Matches Hub 1.0 precedent)</span>

=== Making onPublish and onSubscribe as required parameters ===
* Howard: http://openajax.org/pipermail/interop/2008q4/000702.html
* Jon (here): +1
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Adopt Howard's proposal.</span>

=== Including OpenAjax.js within OpenAjax-mashup.js ===
* Howard: http://openajax.org/pipermail/interop/2008q4/000705.html (last paragraph)
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' OK to combine for short-term development for expediency for now, but must offer a separate OpenAjax.js for people who don't need all of the mashup stuff. Either split off the Hub 1.0 module or duplicate the Hub 1.0 code in both a separate file and within the mashup logic (i.e., developers should use one or the other).</span>

=== OpenAjax.hub.Hub? ===
Isn't "OpenAjax.hub.Hub" a bit confusing? How about "OpenAjax.hub.HubBase"?
* <span style="color:blue">'''RESOLUTION 2008-12-08: ''' Minor detail. Resolve this in email or within open source project.</span>
* <span style="color:red">'''EMAIL AFTER 2008-12-08: ''' Howard explains that he is following Java conventions where interface names are capitalized. Jon says that's a good enough justification.</span>