Difference between revisions of "Org.eclipse.higgins.js.pds.client"

Revision as of 18:44, 26 August 2011

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

Files

• SVN: org.eclipse.higgins.js.pds.connector.common

Design Notes for API additions to this component

Objective

Create a general purpose API that JavaScript programs executed by HBX can use to get and set attributes about the user.

API

JS function _getBX(dev, appId)*

Create new BX object.

Parameters:

• dev : string identifier of the JavaScript developer.
• appId : string identifier of the JavaScript itself.

JS Example:

 var bx = _getBX( 'azigo.com', 'form-filler');

dev property

String identifier of the appJS developer.

JS Example:

 bx.dev = 'azigo.com';

appId property

String identifier of the appJS itself.

JS Example:

 bx.appId = 'form-filler';

getSuggestions(attribute, onready)

Note: For privacy reasons this method may only be called by highly trusted JavaScript.

Parameters:

• attribute: the attribute type string (HTML form element id)
• onready: represents event listener (name of the JS function). if value of 'onready' is empty string, ABX does synchronous request, otherwise ABX does asynchronous request, the result will be passed like parameter to function 'onready'.

JS Example of asynchronous request:

 function onSuggestions(res){
 	//...
 };
 //...
 bx.getSuggestions(attribute, 'onSuggestions');

JS Example of synchronous request:

 res = bx.getSuggestions(attribute, );

getExAttributes(rp, audience, attributes, where, onReady)

Parameters:

• rp: string identifier of the "next hop" attribute data sink. It is expressed in as detailed a form as possible.
  • If the ultimate attribute data consumer is a website then the string is at least a domain, possibly with an additional path:
    • May be a domain+path (e.g. "staples.com/checkout") --the page of a website containing a form to be filled. In this case the "call" would have originated in an app (e.g. Form Filler). the "/checkout" portion adds a bit more framing to the attributes.
• audience: string. Must match either the agent or the rp parameter value or be nil. If not nil, then indicates whether to encrypt tokens for the agent or the rp.
• attributes: set of (attribute, optional, authorities) tuples where:
  • attribute is a URI indicating the attribute type
  • optional is a boolean (if true then this attribute is desired but not required)
  • authorities is a list of domains that are considered by the caller as authoritative WRT this attribute and thus must be used as the source of the attribute, if this list is nil then self asserted values are acceptable. If authority == dev (where dev is the developer of an action-bearing r-card) then only the "host" card of that app will be allowed as the source of attributes.
• where: ?? is a set of (attribute, value-expression) tuples where:
  • attribute: is the attribute URI
  • value-expression (for now) May be an exact value (e.g. "Alice") or may be a regex that the value must match. In the short term the so-called "regex" is just a string of one or more characters followed by an asterisk (e.g. 2*, or 25*)--meaning that the value of the attribute must start with these characters (e.g. values "290" and "250" will match "2*" and "250" (only) will match "25*")
• tokenTypes: a list of token types that are understood by RP. Must be one of:
  • XDI document
• onReady: Represents event listener (name of the JS function). If the value of 'onready' is an empty string, then ABX executes an synchronous query, otherwise ABX does an asynchronous query. The result will be passed as a parameter to the function _onReady_

Returns either:

• a set of zero or more tokens. Each token encodes multiple (attribute, value(s)) tuples where:
  • attribute is the attribute URI \[wiki:this will be one of the attribute URIs pass in to this method\]
  • value(s) are the value(s) of the attribute (may be nil, if no values could be found). Each value may be literal or object typed.

Notes:

• This call allows AppJS developers to request attributes about the user. An app might, for example, as for the user's email address. Calling this function may cause the user's selector to pop up. Whether it does or doesn't depends on the kind of selector the the user is currently using and the user's preference settings.
• By setting the value of the authorities = the AppJS developer's domain (i.e. the "issuer" id of the "host" relationship card that holds or triggers AppJS) then the caller can force the selector to only read attributes from the AppJS's "host" r-card.

Privacy Considerations:

• Depending on how the calling application (aka AppJS) is written, information about the user may remain local (i.e. within the browser and/or on the user's machine) or it may be transmitted to some external web service. The identity of the calling application and the identity of the "rp" are parameters to this call to the selector.
• Since the selector is under the user's control, the user has the ability to have notice and to give consent. The user can be informed as to the identity of the app, the identity of rp (the "next hop" destination if any) and the set of requested (required/optional) attributes.

ABX method delExAttributeValue(attribute, value, onready)

Parameters:

• attribute: the attribute type string (HTML form element id) 
• value: the value to delete
• onready: represents event listener (name of the JS function). if value of 'onready' is empty string, ABX does synchronous request, otherwise ABX does asynchronous request, the result will be passed like parameter to function 'onready'.

Implementation:

• Deletes one specific value of attribute _attribute_

ABX method delExAttribute(attribute, onready)

Parameters:

• attribute: the URI of the attribute
• onready: represents event listener (name of the JS function). if value of 'onready' is empty string, ABX does synchronous request, otherwise ABX does asynchronous request, the result will be passed like parameter to function 'onready'.

Implementation:

• Deletes all values of attribute attribute

Open Issues

1. Do we need to add any locking/blocking (process synchronization) to serialize the calls to getAttributes() across multiple, enabled action cards Javascripts that are all running in parallel.