Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Org.eclipse.higgins.js.pds.client

Revision as of 21:51, 15 September 2011 by Unnamed Poltroon (Talk) (→‎Implementation)

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

Files

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. The APIs are to support various kind of JavaScript apps executed by HBX. These HBX JavaScript apps can fill forms, scrape pages, auto-login to sites, as well as lots of other things with data that they read from a context, transforming it, correcting it, and writing it back in.

Summary:

  • getAttributes() - reads a set of attributes from the local ADS data cache in the browser
  • getSuggestions() - reads back all possible values of a given attribute. Useful for supporting interactive typeahead UI.
  • setAttributes() - writes a set of attributes to the local ADS data cache in the browser

getAttributes(domain, audience, attributes, where, Futures)

Enables a JavaScript app to request attributes (e.g user's email address, gender, etc.) about the user. It searches the person graph to find the requested attributes. If it finds multiple, ambiguous values for one or more attributes, it returns nothing (and the "where' parameter must be used to refine the query).

  • The goal of this rather high-level API is to shield the developer from the complexities of the multi-contextual, multi-person persona data model.
  • 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 "domain" are parameters to this call.
  • FUTURE: By setting the value of the authorities = the JavaScript developer's domain (i.e. the "issuer" id of the context associated with this JavaScript) it will only read attributes from this context.
  • FUTURE: If the attribute release is not part of (i) an explicit pre-existing connection/relationship with the domain or (ii) an implicit relationship (e.g. form filling when the user is viewing the page) then a UI should be implemented informing the user as to the identity of the agent, the identity of domain (the "next hop" destination if any) and the set of requested (required/optional) attributes and allowing them to give consent to this attribute disclosure.

Parameters:

domain
String identifier of ultimate attribute data consumer as far as this is known.
audience
FUTURE (ignored for now) - String. Must match either the agent or the domain parameter value or be nil. If not nil, then indicates whether to encrypt tokens for the agent or the domain.
attributes
Set of (attribute, optional, authorities) tuples where: attribute is a URI indicating the attribute type; the attribute may have one or more role params attached (e.g. ?r=Buyer); optional is a boolean (if true then this attribute is desired but not required)--for now this must be false. authorities will be used in the future; it must be nil for now. it 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 of the form <namespace>#localAtt and namespace is the URL of a page (or a set of pages with a consistent schema). if the entire site uses the same schema then the site domain will suffice;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. At present this must be a JSon document
Futures
Represents a Futures object to handle asynchronous completion of this function

Returns:

  • A set of zero or more tokens (JSON documents at present). Each token encodes multiple (attribute, value(s), ambiguous) 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 or ambiguous). Each value may be literal or object typed.
    • Ambiguous is true if more than one possible value could have been returned. False otherwise.

Implementation

We start with an empty list called rt of (attribute, value, ambiguous) tuples where attribute is the long (URI) form of the attribute; value is the value of the attribute or nil; ambiguous is a boolean that indicates that there were multiple alternative values found (and thus a nil value is returned). We are careful that we pull logically self-consistent manner. That is, we do not pull inter-related attributes from different entities (e.g. person nodes). For example we would never pull a vcard:street from a v:adr object and the vcard:postal-code from another v:adr object.

(1) We try to pull values starting at the person within context

  • context := getConnectionContext(domain) // e.g. http://azigo.com/ptrevithick/staples.com
  • person := context concatenated with "#me" // e.g. http://azigo.com/ptrevithick/staples.com#me
  • If context exists and person has at least one attribute then
    • template := getTemplate(domain)???
    • person := context + "#me"
    • // rolesAtts[] is a set of (roles[], atts[]) pairs where atts is an (attribute, optional, authorities[]) triple
    • rolesAtts[] := sortTriples(attributes)
    • findAttributeValues(rolesAtts, person, template, rt)
  • Endif

(2) We try to pull values starting at the root person in the root context

  • person := rootPerson // root node in root context
  • findAttributeValues(rolesAtts, person, template, rt)

(3) Convert rt into JSON and return rt

findAttributeValues (rolesAtts, topPerson, template, rt)

rolesAtts[] is a list of (roles[], atts[]) pairs where atts is an (attribute, optional, authorities[]) triple

  • Loop: For every pair ra in rolesAtts[]
    • Loop: For every person p reachable from topPerson (including topPerson)
      • If the set of values of the role attribute of p is the same set (or a super-set) of ra.role[]
        • Loop: For every triple t in ra.atts[]
          • att := getLocalAtt(t.attribute) // e.g. "bFirstName"
          • If rt has a tuple whose value is (att, <don't care>, true) then continue looping // we already found too many values for this attribute on some person, so there is no point finding yet more values
          • class := getNamespace(t.attribute) // e.g. http://staples.com/Office-supplies-StaplesCheckoutFlow
          • rule := getRule(template, class, att)
          • value := pullEvalRule(rule, p) // pull within the scope of person
          • If value is not nil then
            • If rt contains a tuple whose attribute matches t.attribute and that has a non-nil value then
              • Replace the value of value in that tuple with nil
              • Set the value of ambiguous in that tuple to true
            • Else
              • Add a new tuple (t.attribute, value, false) to rt
            • Remove tuple t from ra.attributes[]
            • EndIf
          • EndIf
        • EndLoop
      • EndIf
    • EndLoop

getSuggestions(attribute, onready)

This method is only needed for interactive form filling use cases.

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

Parameters:

attribute
attribute URI of the form <namespace>#<localAtt>
onready
represents event listener (name of the JS function). if value of 'onready' is empty string, BX does a synchronous request, otherwise BX does an 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, );

setAttributes(domain, attributes[])

Takes a set of attribute/value pairs. It replaces the existing values of the same attribute (if they exist) otherwise adding them. All other attribute's values are unaffected.

The attribute URIs passed in are in a namespace that is either the FlatPersona vocabulary or in some other vocabulary that is defined in an ontology file that contains mapping rules that describe how to transform between the vocabulary and the Persona data model. A attribute passed as a parameter may map to a traversal path through a graph of objects in the persona data model. For example, if one of the attributes passed in is fp:givenName then this attribute maps to a path that originates in a person node in a context whose identity is derived from domain, follows a vcard:n link (complex attribute) whose value is an instance of vcard:Name, and arrives at the vcard:given-name attribute of this vcard:Name object. If either the person object, the vcard:Name object or both did not exist prior to invoking this method then they would be constructed on-the-fly as a side-effect of this method.

Parameters:

domain
domain of the party providing the attribute value
attributes
And array of (attribute, value) pairs. The attribute is a URI of the form <namespace>#<localAtt>. For scraping <namespace> is the URL of the page being scraped (with query parameters removed). The value is a literal value or object (URI) value.

Implementation:

(1) Phase I

(2) Phase II

  • Loop: For every new person np within newPeople
    • Loop: For every existing person ep reachable from the root me in the root context
      • If np is equivalent to ep then
        • Delete np
      • Else
        • Add an h:correlation link from root me to np

Private Functions

URI getConnectionContext(string domain)

Return:

  • http://<servername>/<pdsuser>/domain

URI getConnectionTemplate(string domain)

Return:

  • http://<servername>/sys/template/domain

string getLocalAtt (URI attribute)

Return everything to the right of the #. (e.g. if the input was http://staples.com/office/supplies/StaplescheckoutFlow#bFirstName then return "bFirstName").

string getRole (URI attribute)

Return the value(s) of "r" (role) parameter on URI. (e.g. if the input was http://www.eclipse.org/higgins/ontologies/2010/6/fp#givenName?r=Buyer then return "Buyer").

URI getNamespace (URI attribute)

Return all but the # and beyond. (e.g. if the input was http://staples.com/office/supplies/StaplescheckoutFlow#bFirstName then return http://staples.com/office/supplies/StaplescheckoutFlow).

string getRule(URI template, URI class, string localAtt)

Find a matching mapping rule in the class entity class within this template. Look through all the values of spin:rule attribute (or sub-attribute, e.g. map:nameRule) of the entity class such that the attribute map:predicate matches localAtt (e.g. bFirstName). For example here is a match: 

     map:nameRule
             [ rdf:type map:rolePathLiteral ;
               map:mappedAtt <http://www.w3.org/2006/vcard/ns#given-name> ;
               map:path <http://www.w3.org/2006/vcard/ns#n> ;
               map:predicate :bFirstName ;
               map:role p:Buyer
             ] ;

The above rule includes the optional role attribute.

URI getTemplate (URI context)

Returns value of template attribute of context

pullEvalRule (string rule, URI person, role[])

We evaluate the rule in "pull" mode (we're pulling values from the PDS) and from person person. Within the rule string there is the name of the rule to fire, and a set of parameter/values and there may be additional role values. We dispatch functions by name.

  • mappingRule := getRuleName(rule) // e.g. "rolePathLiteral"
  • If mappingRule == "rolePathLiteral" then
    • value := pullRolePathLiteral(rule, person, role[])
    • return value
  • If (mappingRule == ... ) then ...

pullRolePathLiteral(rule, person, role[])

Pull value within scope of person (or, if role is not nil from another person node linked from person by an h:correlation link.

Parameters:

  • rule: a rule object. Has subfields
    • rdf:type (e.g. map:rolePathLiteral) - the name of the mapping function
    • map:predicate (E.g. :bFirstName) - the attribute we are trying to get the value of
    • map:role (e.g. p:Buyer) - an optional field that some rules have
    • ...other rule-specific subfields that act as parameters to the mapping function
  • person: we begin the search at the person person
  • role[]: an optional list of roles to further qualify what person nodes to evaluate. This parameter is passed in from pullEvalRule which just passes it through from its caller which may have extracted the role by calling getRole on the original attribute URI. The rule itself may contain a map:role field. These two sources of role values are combined.

Implementation:

  • r[] := getRoleParam(rule) plus values (if any) from role[] // merge role array from role in rule + role[] param
  • path := getPathParam(rule)
  • mappedAtt := getMappedAtt(rule)
  • If role is not nil then
    • If person has all role(s) r[] then p := person // person must match all roles
    • Else
      • p := find person linked via h:correlation from person node the value(s) of whose role attribute match or are a superset of the set r[]
      • if p == nil then return nil
    • EndIf
    • p := person
  • EndIf
  • obj := value of path attribute of entity
  • If obj is nil Return nil
  • Return the value of mappedAtt attribute of obj

URI pushEvalRule (URI context, string rule, value)

We evaluate the rule in "push" mode (we're pushing values in to the PDS). Within the rule string there is the name of the rule to fire, and a set of parameter/values. We call dispatch functions by name.

  • mappingRule := getRuleName(rule) // e.g. "rolePathLiteral"
  • If mappingRule == "rolePathLiteral" then
    • newPerson := pushRolePathLiteral(context, rule, value)
    • return newPerson
  • ElseIf mappingRule == ...

URI pushRolePathLiteral(URI context, string rule, value)

Push value into PDS.

  • role := getRoleParam(rule)
  • path := getPathParam(rule)
  • mappedAtt := getMappedAtt(rule)
  • If role == nil then
    • If path exists from :me within context context
      • Then follow it
      • Else build portions of the path as needed // build objects along the path to create the path as needed
    • Replace the value of mappedAtt with new value
  • Else
    • Find a person from :me one hop out along h:correlation links that has role value of role
    • If it isn't there then
      • newContext := a new context
      • newPerson := a new :me person within newContext
      • Create an h:correlation link from the :me within context to the :me within newContext
    • Else
      • Walk path/mappedAtt and set the value
      • newPerson := nil
  • EndIf
  • Return newPerson
Retrieved from "https://wiki.eclipse.org/index.php?title=Org.eclipse.higgins.js.pds.client&oldid=268454"

Back to the top