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

Revision as of 17:11, 29 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

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, BX does synchronous request, otherwise BX 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, );

getAttributes(rp, audience, attributes, where, onReady, interactive)

• Enables a JavaScript app to request attributes (e.g user's email address or gender) about the user.
• 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 JavaScript developer's domain (i.e. the "issuer" id of the "host" relationship card that holds or triggers JavaScript) then the caller can force the selector to only read attributes from the JavaScript's "host" r-card.

Privacy Considerations:

• Depending on how the calling JavaScript 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.

Parameters:

rp

String identifier of immediate attribute data consumer. It is expressed in as detailed a form as possible. If the ultimate consumer is a website then the string is at least a domain, possibly with an additional path. The 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. The value of a member of authorities is matched against the issuer of the containing context of the entity.

where 

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 a Json document

onReady

Represents event listener (name of the JS function). If the value of 'onready' is an empty string, then it executes an synchronous query, otherwise it does an asynchronous query. The result will be passed as a parameter to the function onReady

interactive 

Boolean. If true then it is okay to involve the user, e.g. to popup a dialog box with some selections to disambiguate between two possible shipping addresses that could be used as sources for the attributes desired.

Returns:

• A set of zero or more tokens. Each token encodes multiple (attribute, value(s)) tuples where:
  • Attribute is the attribute URI (note: this will be one of the attribute URIs passed 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.

IMPLEMENTATION: getAttributes(rp, audience, attributes, where, onReady, interactive)

Overview

1. See if context for RP already exists. If so skip to step 4
2. Determine candidate entities by a combination of mapping and authority matching
3. Determine winning entities from redundant possible target entities
   1. Determine if we need to pop up the selector UI
   2. Pop up selector UI if necessary
   3. Else automatically select best entities
4. Copy attributes from winning entities into RP context skipping any ambiguous attributes
5. Read attributes from the RP context, map these attributes, and
6. Return them

Step 1: Attempt find the needed attribute values from the RP context (@@@connection context pair?)

• template := getTemplateId(rp)

Loop: For every triple t in attributes

• If t.authorities is nil then
  • att := getShortName(t.attribute) (e.g. "bFirstName")
  • pathset := mapAttribute(att, template, capitalize(getRPEntity(rp)))
  • attributeHolder := getAttributeHolder(domainEntity, pathset\[0\]) (e.g. the entity that directly holds the vcard:given-name attribute & value) (we are assuming here that pathset.size = 1) (this function will return nil if there is ambiguity)
  • If attributeHolder = nil then continue looping
  • value := read value of attribute att from attributeHolder
  • insert value into a token (each token has a different target entity)
  • remove t from attributes[] (for this attribute we're done)
• Else
  • continue looping

End loop

Private Functions

=entity getRPEntity(string rp)

Returns the id of the entity representing the user within the Definer context @@@@TODO both? within a connector context pair.

Parameter:

rp

URI of relying party website of the form http(s)://<domain>/<path>?<more stuff>.

Implementation:

• Try to open the context of ContextId := http://<pdsdomain>/<pdsuser>/<domain> (e.g. http://azigo.com/ptrevithick/staples.com)
• If open succeeds then
  • entity := string-normalization(<path>) (e.g. entity := "office-supplies-StaplesCheckoutFlow")
  • See if entity exists
  • If it exists then
    • return entity

Return nil

pathset mapAttribute(att, templateContext, className)

Parameters:

att

string - short name of attribute in the original ontology

templateContext

contextId of the template context

className

- string name of the domainEntity's class (e.g. "Office-supplies-StaplesCheckoutFlow")

This routine is the heart of the mapping process. It takes an short name att in one ontology (using the term loosely here) (e.g. the "facebook.com" ontology) and finds an equivalent set of attribute paths in the Persona Data Model. For example it could take facebook's notion of "firstname" and find that this has the same semantics as the PDM's "vcard:given-name" attribute. Thus the string value "Alice" found on some p:Person in some context could be safely copied/used as the value of the "firstname" field on form on a facebook.com web page.

(1) Look for attribute att in the class className

• class := find entity where entityId == className within the templateContext

(2) Look for a spin:rule within class: (a "spin:rule" is an attribute of the class) of class such that the attribute map:predicate matches att (e.g. bFirstName). For example here is a match:

 spin:rule
             [ a       map:FromPersona3Hops@@@@ ;
               map:path1 p:billing ;
               map:path2 p:billingName ;
               map:path3 vcard:given-name ;
               map:predicate :bFirstName
             ] .

(2a) If it is a FromPersona3Hops@@@@ rule then return pathset(0).path :=

 (map:path1)+(map:path2)+(map:path3) [e.g. "(p:billing)(p:billingName)(vcard:given-name)"]

(2b) If it is a FromPersona2Hops rule then return pathset(0).path :=

 (map:path1)+(map:path2) [e.g. "(p:billingName)(vcard:given-name)"]

delExAttributeValue(attribute, value, onready)

• Deletes one specific value of attribute attribute

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.

delExAttribute(attribute, onready)

Deletes all values of attribute attribute

Parameters:

attribute

the URI of the attribute

onready

represents event listener (name of the JS function). if value of onready is an empty string, it does synchronous request, otherwise it does asynchronous request, the result will be passed like parameter to function onready.

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.