Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "IdAS XDI Mapping"

(Links)
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{#eclipseproject:technology.higgins}}
+
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}  
This page documents the mapping between the [[Higgins Data Model]] (which is implemented by [[IdAS]]) and XDI. XDI ("XRI Data Interchange") is a data model and protocol for sharing, linking, and synchronizing data over the Internet ("structured web") and other networks using Extensible Resource Identifiers (XRIs). It is being developed by the [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xdi OASIS XDI Technical Committee].
+
  
The [[IdAS XDI Engine]] exposes an IdAS Context at an XDI endpoint. It processes and applies incoming XDI messages.
+
=== Status ===
 +
* This document needs to be updated to show a representative [[Persona Data Model 2.0]] data structure instead of the "made up" structure shown in the diagram below.
 +
* The endpoints are all broken at present (old parityinc, graceland links)
  
The [[XDI Context Provider]] implements an IdAS Context by sending XDI messages. These message can be sent either to an XDI endpoint exposed by the [[IdAS XDI Engine]] or to a native XDI endpoint.
+
=== Introduction ===
 +
This page documents the mapping between the Higgins [[Context Data Model]] (which is implemented by [[IdAS]]) and XDI. XDI ("XRI Data Interchange") is a data model and protocol for sharing, linking, and synchronizing data over the Internet ("structured web") and other networks using Extensible Resource Identifiers (XRIs). It is being developed by the [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xdi OASIS XDI Technical Committee].  
  
== Mapping ==
+
The [[Org.eclipse.higgins.as|Attribute Service]] exposes an IdAS Context at an XDI endpoint. It processes and applies incoming XDI messages.
  
=== Concepts ===
+
The [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]] implements an IdAS Context by sending XDI messages. These message can be sent either to an XDI endpoint exposed by the [[Org.eclipse.higgins.as|Attribute Service]] or to a native XDI endpoint.
  
Since the Higgins Data Model is based on RDF/OWL, and since XDI is also (conceptually) based on RDF, the basic mapping is straight-forward. However, some attention has to be paid to details.
+
== Mapping  ==
  
A Higgins [[Context]] can be mapped to an XDI graph using the following rules:
+
=== Concepts  ===
* An [[Entity]] maps to an XDI subject. The XDI subject's XRI is the Entity ID cast to an XRI.
+
* An [[Attribute]] maps to an XDI predicate. The XDI predicate's XRI is the Attribute ID cast to an XRI.
+
* In general, each Value of an [[Attribute]] maps to an XDI subject inside an XDI inner graph. The XDI subject's XRI is a HIN calculated from the Value.
+
** If the Value is a Simple Value, then the XDI subject in the XDI inner graph has a single XDI predicate with an XDI literal. The XDI predicate's XRI is the the special $value XDI predicate.
+
** If the Value is a Complex Value, then the rules for mapping the Attributes of that Complex Value apply recursively, i.e. each Attribute of the Complex Value maps to an XDI predicate.
+
* Special case 1: If an [[Attribute]] contains only a single Simple Value, then that [[Attribute]] does not need an inner graph. Instead the Value maps directly to an XDI literal on the XDI predicate that represents the [[Attribute]].
+
* Special case 2: If an [[Attribute]] is a [[Entity Relation]], then that [[Attribute]] does not need an inner graph. Instead the Values map directly to XDI references on the XDI predicate that represents the [[Attribute]].
+
* An [[Entity Correlation]] maps to an XDI statement with the special $is XDI predicate
+
* The type of an [[Entity]] maps to an XDI statement with the special $is$a XDI predicate
+
  
=== Example ===
+
Since the Higgins Data Model is based on RDF/OWL, and XDI is also based on RDF, the basic mapping is straightforward. However, some attention has to be paid to details.
  
Example Context diagram:
+
A Higgins [[Context]] can be mapped to an XDI graph using the following rules:  
  
[[Image:IdAS_XDI.png]]
+
*An [[Entity]] maps to an XDI subject. The XDI subject's XRI is the Entity ID cast to an XRI.
 +
*An [[Attribute]] maps to an XDI predicate. The XDI predicate's XRI is the Attribute ID cast to an XRI.
 +
*In general, each Value of an [[Attribute]] maps to an XDI subject inside an XDI inner graph. The XDI subject's XRI is a HIN (Hash I-Number) calculated from the Value.
 +
**If the Value is a Simple Value, then the XDI subject in the XDI inner graph has a single XDI predicate with an XDI literal. The XDI predicate's XRI is the the special $value XDI predicate.
 +
**If the Value is a Complex Value, then the rules for mapping the Attributes of that Complex Value apply recursively, i.e. each Attribute of the Complex Value maps to an XDI predicate.
 +
*Special case 1: If an [[Attribute]] contains only a single Simple Value, then that [[Attribute]] does not need an inner graph. Instead the Value maps directly to an XDI literal on the XDI predicate that represents the [[Attribute]].
 +
*Special case 2: If an [[Attribute]] is an [[Entity Relation]], then that [[Attribute]] does not need an inner graph. Instead the Values map directly to XDI references on the XDI predicate that represents the [[Attribute]].
 +
*An [[Entity Correlation]] maps to an XDI statement with the special $is XDI predicate
 +
*The type of an [[Entity]] maps to an XDI statement with the special $is$a XDI predicate
 +
*The type of a Value maps to an XDI statement with the special $is$a XDI predicate
  
Example Context description:
+
=== Example ===
  
* The Context has three Entities '''=paul''', '''=sergey''' and '''=drummond'''.
+
Example Context diagram:  
* '''=paul''' has an Attribute '''+name''', which has a single Simple Value :'''"Paul T."'''.
+
* '''=paul''' has an Entity Relation '''+friend''' to '''=sergey''' and '''=drummond'''.
+
* '''=paul''' has an Attribute '''+phone''', which has two Values:
+
** The first Value is a Simple Value: '''"+1 (617) 513 7924"'''.
+
** The second Value is a Simple Value: '''"+1 (781) 559 0153"'''.
+
* '''=paul''' has an Attribute '''+address''', which has three Values:
+
** The first Value is a Simple Value: '''"56 Kearney Rd, Needham, Massachusetts 02494, USA"'''.
+
** The second Value is a Complex Value. It has four Attributes '''+street''', '''+city''', '''+state''' and '''+zip'''.
+
*** The first Attribute has a single Simple Value: '''"56 Kearney Rd"'''.
+
*** The second Attribute has a single Simple Value: '''"Needham"'''.
+
*** The third Attribute has a single Simple Value: '''"MA"'''.
+
*** The fourth Attribute has a single Simple Value: '''"02494"'''.
+
** The third Value is a Complex Value. It has two Attributes '''+line''' and '''+country'''.
+
*** The first Attribute has two Simple Values.
+
**** The first Value is a Simple Value: '''"56 Kearney Rd"'''.
+
**** The second Value is a Complex Value: '''"Needham, Massachusetts 2494"'''.
+
*** The second Attribute has a single Simple Value: '''"USA"'''.
+
  
Example Context in XDI:
+
[[Image:IdAS XDI.png]]
  
<pre>
+
Example Context description:
=paul    <-- An Entity -->
+
 
   +name    <-- A "Special Case 1" Attribute -->
+
*The Context has three Entities '''=paul''', '''=sergey''' and '''=drummond'''.
       "Paul T."    <-- A single Simple Value -->
+
*'''=paul''' has an Attribute '''+name''', which has a single Simple Value&nbsp;:'''"Paul T."'''.
   +friend    <-- A "Special Case 2" Attribute -->
+
*'''=paul''' has an Entity Relation '''+friend''' to '''=sergey''' and '''=drummond'''.
       =sergey    <-- An Entity Relation Value -->
+
*'''=paul''' has an Attribute '''+phone''', which has two Values:
       =drummond    <-- An Entity Relation Value -->
+
**The first Value is a Simple Value: '''"+1 (617) 513 7924"'''.
   +phone    <-- An Attribute with two Values -->
+
**The second Value is a Simple Value: '''"+1 (781) 559 0153"'''.
 +
*'''=paul''' has an Attribute '''+address''', which has three Values:
 +
**The first Value is a Simple Value: '''"56 Kearney Rd, Needham, Massachusetts 02494, USA"'''.
 +
**The second Value is a Complex Value. It has four Attributes '''+street''', '''+city''', '''+state''' and '''+zip'''.
 +
***The first Attribute has a single Simple Value: '''"56 Kearney Rd"'''.
 +
***The second Attribute has a single Simple Value: '''"Needham"'''.
 +
***The third Attribute has a single Simple Value: '''"MA"'''.
 +
***The fourth Attribute has a single Simple Value: '''"02494"'''.
 +
**The third Value is a Complex Value. It has two Attributes '''+line''' and '''+country'''.
 +
***The first Attribute has two Values.
 +
****The first Value is a Simple Value: '''"56 Kearney Rd"'''.
 +
****The second Value is a Simple Value: '''"Needham, Massachusetts 2494"'''.
 +
***The second Attribute has a single Simple Value: '''"USA"'''.
 +
 
 +
Example Context in XDI:
 +
<pre>=paul    &lt;-- An Entity --&gt;
 +
   +name    &lt;-- A "Special Case 1" Attribute --&gt;
 +
       "Paul T."    &lt;-- A single Simple Value --&gt;
 +
   +friend    &lt;-- A "Special Case 2" Attribute --&gt;
 +
       =sergey    &lt;-- An Entity Relation Value --&gt;
 +
       =drummond    &lt;-- An Entity Relation Value --&gt;
 +
   +phone    &lt;-- An Attribute with two Values --&gt;
 
       /
 
       /
         $value$hash$sha256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d    <-- First Value of +phone: A Simple Value -->
+
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d    &lt;-- First Value of +phone: A Simple Value --&gt;
 
             $value
 
             $value
 
               "+1 (617) 513 7924"
 
               "+1 (617) 513 7924"
         $value$hash$sha256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca    <-- Second Value of +phone: A Simple Value -->
+
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca    &lt;-- Second Value of +phone: A Simple Value --&gt;
 
             $value
 
             $value
 
               "+1 (781) 559 0153"
 
               "+1 (781) 559 0153"
   +address    <-- An Attribute with three Values -->
+
   +address    &lt;-- An Attribute with three Values --&gt;
 
       /
 
       /
         $value$hash$sha256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c    <-- First Value of +address: A Simple Value -->
+
         $value$hash$sha$256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c    &lt;-- First Value of +address: A Simple Value --&gt;
 
             $value
 
             $value
 
               "56 Kearney Rd, Needham, Massachusetts 02494, USA"
 
               "56 Kearney Rd, Needham, Massachusetts 02494, USA"
         $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715    <-- Second Value of +address: A Complex Value with four Attributes -->
+
         $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715    &lt;-- Second Value of +address: A Complex Value with four Attributes --&gt;
             +street    <-- A "Special Case 1" Attribute -->
+
             +street    &lt;-- A "Special Case 1" Attribute --&gt;
               "56 Kearney Rd"    <-- A single Simple Value -->
+
               "56 Kearney Rd"    &lt;-- A single Simple Value --&gt;
             +city    <-- A "Special Case 1" Attribute -->
+
             +city    &lt;-- A "Special Case 1" Attribute --&gt;
               "Needham"    <-- A single Simple Value -->
+
               "Needham"    &lt;-- A single Simple Value --&gt;
             +state    <-- A "Special Case 1" Attribute -->
+
             +state    &lt;-- A "Special Case 1" Attribute --&gt;
               "MA"    <-- A single Simple Value -->
+
               "MA"    &lt;-- A single Simple Value --&gt;
             +zip    <-- A "Special Case 1" Attribute -->
+
             +zip    &lt;-- A "Special Case 1" Attribute --&gt;
               "02494"    <-- A single Simple Value -->
+
               "02494"    &lt;-- A single Simple Value --&gt;
         $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324    <-- Third Value of +address: A Complex Value with two Attributes -->
+
         $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324    &lt;-- Third Value of +address: A Complex Value with two Attributes --&gt;
             +line    <-- An Attribute with two values -->
+
             +line    &lt;-- An Attribute with two values --&gt;
 
               /
 
               /
                   $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c    <-- First Value of +line: A Simple Value -->
+
                   $value$hash$sha$256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c    &lt;-- First Value of +line: A Simple Value --&gt;
 
                     $value
 
                     $value
 
                         "56 Kearney Rd"
 
                         "56 Kearney Rd"
                   $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32    <-- Second Value of +line: A Simple Value -->
+
                   $value$hash$sha$256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32    &lt;-- Second Value of +line: A Simple Value --&gt;
 
                     $value
 
                     $value
 
                         "Needham, Massachusetts 02494"
 
                         "Needham, Massachusetts 02494"
             +country    <-- A "Special Case 1" Attribute -->
+
             +country    &lt;-- A "Special Case 1" Attribute --&gt;
               "USA"    <-- A single Simple Value -->
+
               "USA"    &lt;-- A single Simple Value --&gt;
=sergey    <-- An Entity -->
+
=sergey    &lt;-- An Entity --&gt;
=drummond    <-- An Entity -->
+
=drummond    &lt;-- An Entity --&gt;
</pre>
+
</pre>  
 +
=== Hash I-Numbers for Simple Values  ===
  
=== Hash I-Numbers for Simple Values ===
+
On several occasions in this mapping, it is necessary to refer to individual Simple Values of a multi-valued Attribute. Since Simple Values in Higgins IdAS do not have persistent identifiers, a mechanism called "Hash I-Number" (HIN) is used. A HIN is an i-number that is deterministically calculated from a value, therefore acting as an index of that Value in an XDI inner graph.
  
On several occasions in this mapping, it is necessary to refer to individual Simple Values of a multi-valued Attribute. Since Simple Values in Higgins IdAS do not have persistent identifiers, a mechanism called "Hash I-Number" (HIN) is used. A HIN is an i-number that is deterministically calculated from a value, therefore acting as an index of that Value in an XDI inner graph.
+
This pseudocode can be used to calculate a HIN for a Simple Value:
 +
<pre>FUNCTION makeSimpleValueHin(simpleValue)
  
This pseudocode can be used to calculate a HIN for a Simple Value:
+
   String hin = "$value$hash$sha$256" + "!" + hex(sha256(simpleValue.lexical));
 
+
<pre>
+
FUNCTION makeSimpleValueHin(simpleValue)
+
 
+
   String hin = "$value$hash$sha256" + "!" + hex(sha256(simpleValue.string));
+
 
   RETURN hin;
 
   RETURN hin;
 
END
 
END
</pre>
+
</pre>  
 
+
Examples:  
Examples:
+
* "Sergey" becomes '''$value$hash$sha256!f3357799ddcf994ae4d759e37d58c29938419f5af9681ae65a6f0f1677b213b7'''
+
* "Markus" becomes '''$value$hash$sha256!f00b1896cf1c0569b9bdcfdde4ed948a266bae9707b3567240211efc8ffc06a0'''
+
* "+1 (617) 513 7924" becomes '''$value$hash$sha256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d'''
+
* "+1 (781) 559 0153" becomes '''$value$hash$sha256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca'''
+
  
=== Hash I-Numbers for Complex Values ===
+
*"Sergey" becomes '''$value$hash$sha$256!f3357799ddcf994ae4d759e37d58c29938419f5af9681ae65a6f0f1677b213b7'''
 +
*"Markus" becomes '''$value$hash$sha$256!f00b1896cf1c0569b9bdcfdde4ed948a266bae9707b3567240211efc8ffc06a0'''
 +
*"+1 (617) 513 7924" becomes '''$value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d'''
 +
*"+1 (781) 559 0153" becomes '''$value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca'''
  
Hash I-Numbers are also used to refer to individual Complex Values. Like with Simple Values, HINs for Complex Values are calculated from the Value and can then be used as an index of that Value in an XDI inner graph.
+
=== Hash I-Numbers for Complex Values ===
  
This pseudocode can be used to calculate a HIN for a Complex Value:
+
Hash I-Numbers are also used to refer to individual Complex Values. Like with Simple Values, HINs for Complex Values are calculated from the Value and can then be used as an index of that Value in an XDI inner graph.
  
<pre>
+
This pseudocode can be used to calculate a HIN for a Complex Value:
FUNCTION makeComplexValueHin(complexValue):
+
<pre>FUNCTION makeComplexValueHin(complexValue):
  
   String hin = "$value$hash$sha256" + "!" + hex(sha256(makeComplexString(complexValue)));
+
   String hin = "$value$hash$sha$256" + "!" + hex(sha256(makeComplexString(complexValue)));
 
   RETURN hin;
 
   RETURN hin;
 
END
 
END
Line 132: Line 133:
  
 
   String buffer = "";
 
   String buffer = "";
   Set attributeIdStrings;  # a set of strings representing the attribute ids of this complex value
+
   Set attributeIds;  # a set of strings representing the attribute ids of this complex value
  
 
   FOR EACH attribute IN complexValue.attributes
 
   FOR EACH attribute IN complexValue.attributes
  
     attibuteIdStrings.push(attrIdToXri(attribute.attributeId))
+
     attibuteIds.push(attrIdToXri(attribute.attributeId))
 
   END
 
   END
  
   FOR EACH attributeId IN sort(attributeIdStrings)
+
   FOR EACH attributeId IN sort(attributeIds)
  
 
     buffer += attributeId + ' ';
 
     buffer += attributeId + ' ';
 
     Set simpleValuesStrings;  # a set of strings representing the simple values of this complex value
 
     Set simpleValuesStrings;  # a set of strings representing the simple values of this complex value
 
     Set complexValuesStrings;  # a set of strings representing the complex values of this complex value
 
     Set complexValuesStrings;  # a set of strings representing the complex values of this complex value
 +
 +
    Attribute attribute = complexValue.getAttribute(attributeId)
  
 
     FOR EACH value IN attribute.values
 
     FOR EACH value IN attribute.values
  
 
       IF value.isSimple THEN
 
       IF value.isSimple THEN
         simpleValuesStrings.push('"' + value.string + '"' + ' ')
+
         simpleValuesStrings.push('"' + value.lexical + '"' + ' ')
 
       ELSE IF value.isComplex THEN
 
       ELSE IF value.isComplex THEN
 
         complexValuesStrings.push(makeComplexValueString(value) + ' ')
 
         complexValuesStrings.push(makeComplexValueString(value) + ' ')
Line 160: Line 163:
 
   RETURN buffer;
 
   RETURN buffer;
 
END
 
END
</pre>
+
</pre>  
 +
Examples:
  
Examples:
+
*For the second Value of '''+address''',
 +
**the result of the makeComplexValueString() function is '''+city{space}"Needham"{space}+state{space}"MA"{space}+street{space}"56 Kearney Rd"{space}+zip{space}"02494"{space}'''
 +
**the result of the makeComplexValueHin() function is '''$value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715'''
  
* For the second Value of '''+address''',
+
*For the third Value of '''+address''',  
** the result of the makeComplexValueString() function is '''+city{space}"Needham"{space}+state{space}"MA"{space}+street{space}"56 Kearney Rd"{space}+zip{space}"02494"{space}'''
+
**the result of the makeComplexString() function is '''+country{space}"USA"{space}+line{space}"56 Kearney Rd"{space}"Needham, Massachusetts 02494"{space}'''  
** the result of the makeComplexValueHin() function is '''$value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715'''
+
**the result of the makeComplexHin() function is '''$value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324'''
  
* For the third Value of '''+address''',
+
== Test endpoints  ==
** the result of the makeComplexString() function is '''+country{space}"USA"{space}+line{space}"56 Kearney Rd"{space}"Needham, Massachusetts 02494"{space}'''
+
** the result of the makeComplexHin() function is '''$value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324'''
+
  
Note that this mechanism is only used for Complex Values without an Entity ID.
+
The following XDI endpoints are available for testing:
  
== Operations ==
+
=== IdAS Attribute Service  ===
  
Using IdAS, a Higgins context can be opened, and operations can be performed on it. The equivalent in XDI is XDI messages (which contain XDI operations).  
+
*http://graceland.parityinc.net/xdi-idas/context-inmem: Attribute Service exposing a '''higgins.idas.cp.inmem''' Context. ''Note:'' The inmem CP does not support listing all Entities.
 +
*http://graceland.parityinc.net/xdi-idas/context-xmlfile: Attribute Service exposing a '''higgins.idas.cp.xmlfile''' Context.
 +
*http://graceland.parityinc.net/xdi-idas/context-ldap: Attribute Service exposing a '''higgins.idas.cp.jndi''' Context. ''Note:'' The Context is Parity's LDAP server at ldap://graceland.parityinc.net:389.
 +
*http://graceland.parityinc.net/xdi-idas/context-rdf: Attribute Service exposing a '''higgins.idas.cp.rdf''' Context. ''Note:'' The Context is the RDF document at http://graceland.parityinc.net/~msabadello/rdf/test.rdf. This CP is read-only.
  
All XDI examples are in the X3 Simple serialization format. See [http://wiki.oasis-open.org/xdi/X3Format X3Format] for more information about X3 serialization formats.
+
=== Native XDI Endpoints  ===
  
=== Entities ===
+
*http://graceland.parityinc.net/xdi-endpoint/mem-graph-hin: '''Native XDI endpoint''' with HIN support enabled. Backed by an in-memory store.
 +
*http://graceland.parityinc.net/xdi-endpoint/bdb-graph-hin: '''Native XDI endpoint''' with HIN support enabled. Backed by a Berkely DB store.
  
==== List all Entities ====
+
== Operations  ==
  
This example gets all Entities in the Context.
+
Using IdAS, a Higgins context can be opened, and operations can be performed on it. The equivalent in XDI is XDI messages (which contain XDI operations).  
  
[[IdAS]] calls:
+
All XDI examples are in the X3 Simple serialization format. See [http://wiki.oasis-open.org/xdi/X3Format X3Format] for more information about X3 serialization formats.
  
<pre>
+
=== Entities  ===
Iterator<Entity> entities = context.getEntities(null);
+
</pre>
+
  
Message sent by the [[XDI Context Provider]]:
+
==== List all Entities  ====
  
<pre>
+
This example gets all Entities in the Context.
=sender
+
 
 +
[[IdAS]] calls:
 +
<pre>Iterator&lt;Entity&gt; entities = context.getEntities(null);
 +
</pre>
 +
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
 +
<pre>=sender
 
$get
 
$get
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint:
 +
<pre>=paul
 +
=sergey
 +
=drummond
 +
</pre>
 +
==== Get one Entity from the Context  ====
  
Reply from the [[XDI Engine]] / native XDI endpoint:
+
This example gets the Entity '''=paul''' in the Context.
  
<pre>
+
[[IdAS]] calls:
=paul
+
<pre>IEntity entity = context.getEntity("=paul");
  +name
+
</pre>
      "Paul T."
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
  +friend
+
<pre>=sender
      =sergey
+
   $get$a$xsd$boolean
      =drummond
+
   +phone
+
 
       /
 
       /
         $value$hash$sha256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
+
         =paul
            $value
+
</pre>
              "+1 (617) 513 7924"
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint:
        $value$hash$sha256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca
+
<pre>$true
            $value
+
</pre>  
              "+1 (781) 559 0153"
+
==== Remove an Entity from the Context  ====
  +address
+
      /
+
        $value$hash$sha256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c
+
            $value
+
              "56 Kearney Rd, Needham, Massachusetts 02494, USA"
+
        $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
+
            +street
+
              "56 Kearney Rd"
+
            +city
+
              "Needham"
+
            +state
+
              "MA"
+
            +zip
+
              "02494"
+
        $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
+
            +line
+
              /
+
                  $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
+
                    $value
+
                        "56 Kearney Rd"
+
                  $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
+
                    $value
+
                        "Needham, Massachusetts 02494"
+
            +country
+
              "USA"
+
=sergey
+
=drummond
+
</pre>
+
  
==== Get one Entity from the Context ====
+
This example removes Entity '''=paul''' from the Context.
  
This example gets Entity '''=paul''' in the Context.
+
[[IdAS]] calls:
 +
<pre>IEntity entity = context.getEntity("=paul");
 +
entity.remove();
 +
context.applyUpdates();
 +
</pre>
 +
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
 +
<pre>=sender
 +
  $del
 +
      /
 +
        =paul
 +
</pre>
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
[[IdAS]] calls:
+
=== Attributes  ===
  
<pre>
+
==== List all Attributes from an Entity  ====
IEntity entity = context.getEntity("=paul");
+
</pre>
+
  
Message sent by the [[XDI Context Provider]]:
+
This example gets all Attributes of the Entity '''=paul'''.
  
<pre>
+
[[IdAS]] calls:
=sender
+
<pre>IEntity entity = context.getEntity("=paul");
 +
Iterator&lt;IAttribute&gt; attributes = entity.getAttributes();
 +
</pre>
 +
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
 +
<pre>=sender
 
   $get
 
   $get
 
       /
 
       /
 
         =paul
 
         =paul
</pre>
+
</pre>  
 +
*After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later
  
Reply from the [[XDI Engine]] / native XDI endpoint:
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint:  
 
+
<pre>=paul
<pre>
+
=paul
+
 
   +name
 
   +name
      "Paul T."
 
 
   +friend
 
   +friend
      =sergey
 
      =drummond
 
 
   +phone
 
   +phone
      /
 
        $value$hash$sha256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
 
            $value
 
              "+1 (617) 513 7924"
 
        $value$hash$sha256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca
 
            $value
 
              "+1 (781) 559 0153"
 
 
   +address
 
   +address
 +
</pre>
 +
==== Get one Attribute from an Entity  ====
 +
 +
This example gets the Attribute '''+phone''' of the Entity '''=paul'''.
 +
 +
[[IdAS]] calls:
 +
<pre>IEntity entity = context.getEntity("=paul");
 +
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 +
</pre>
 +
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
 +
<pre>=sender
 +
  $get$a$xsd$boolean
 
       /
 
       /
         $value$hash$sha256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c
+
         =paul
            $value
+
             +phone
              "56 Kearney Rd, Needham, Massachusetts 02494, USA"
+
</pre>  
        $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
+
*After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later
             +street
+
              "56 Kearney Rd"
+
            +city
+
              "Needham"
+
            +state
+
              "MA"
+
            +zip
+
              "02494"
+
        $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
+
            +line
+
              /
+
                  $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
+
                    $value
+
                        "56 Kearney Rd"
+
                  $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
+
                    $value
+
                        "Needham, Massachusetts 02494"
+
            +country
+
              "USA"
+
</pre>
+
  
==== Remove an Entity from the Context ====
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint:
 +
<pre>$true
 +
</pre>
 +
==== Remove an Attribute from an Entity  ====
  
This example removes Entity '''=paul''' from the Context.
+
This example removes the Attribute '''+phone''' from the Entity '''=paul'''.  
  
[[IdAS]] calls:
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
<pre>
+
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
IEntity entity = context.getEntity("=paul");
+
attribute.remove();
entity.remove();
+
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
Message sent by the [[XDI Context Provider]]:
+
<pre>=sender
 
+
<pre>
+
=sender
+
 
   $del
 
   $del
 
       /
 
       /
         =markus
+
         =paul
</pre>
+
            +phone
 +
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
=== Values  ===
  
=== Attributes ===
+
==== List all Values from an Attribute  ====
  
==== Get one Attribute from an Entity ====
+
This example gets all Values of the Attribute '''+phone''' on the Entity '''=paul'''.
  
This example gets the Attribute '''+phone''' of the Entity '''=paul'''.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
</pre>
+
Iterator&lt;IAttributeValue&gt; values = attribute.getValues();
 
+
</pre>  
Message sent by the [[XDI Context Provider]]:
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
 
+
<pre>=sender
<pre>
+
=sender
+
 
   $get
 
   $get
 
       /
 
       /
 
         =paul
 
         =paul
 
             +phone
 
             +phone
</pre>
+
</pre>  
 +
*After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later
  
* After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint:  
 
+
<pre>=paul
Reply from the [[XDI Engine]] / native XDI endpoint:
+
 
+
<pre>
+
=paul
+
 
   +phone
 
   +phone
 
       /
 
       /
         $value$hash$sha256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
+
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d     &lt;-- First Value of +phone: A Simple Value --&gt;
 
             $value
 
             $value
 
               "+1 (617) 513 7924"
 
               "+1 (617) 513 7924"
         $value$hash$sha256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca
+
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca     &lt;-- Second Value of +phone: A Simple Value --&gt;
 
             $value
 
             $value
 
               "+1 (781) 559 0153"
 
               "+1 (781) 559 0153"
</pre>
+
</pre>
 +
<br>  
  
==== Remove an Attribute from an Entity ====
+
=== Simple Values  ===
  
This example removes the Attribute '''+phone''' from the Entity '''=paul'''.
+
==== Remove a Simple Value from an Attribute  ====
  
[[IdAS]] calls:
+
This example removes the Simple Value '''+1 (781) 559 0153''' from the Attribute '''+phone''' on the Entity '''=paul'''.
  
<pre>
+
[[IdAS]] calls:  
IEntity entity = context.getEntity("=paul");
+
<pre>IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
+
attribute.remove();
+
context.applyUpdates();
+
</pre>
+
 
+
Message sent by the [[XDI Context Provider]]:
+
 
+
<pre>
+
=sender
+
  $del
+
      /
+
        =paul
+
            +phone
+
</pre>
+
 
+
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
 
+
=== Simple Values ===
+
 
+
==== Remove a Simple Value from an Attribute ====
+
 
+
This example removes the Simple Value '''+1 (781) 559 0153''' from the Attribute '''+phone''' on the Entity '''=paul'''.
+
 
+
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next(); // value is "+1 (781) 559 0153"
 
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next(); // value is "+1 (781) 559 0153"
 
value.remove();
 
value.remove();
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 +
*Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)
  
* Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
 
+
<pre>=sender
Message sent by the [[XDI Context Provider]]:
+
 
+
<pre>
+
=sender
+
 
   $del
 
   $del
 
       /
 
       /
Line 422: Line 366:
 
             +phone
 
             +phone
 
               /
 
               /
                   $value$hash$sha256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca <-- HIN of +1 (781) 559 0153 -->
+
                   $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca &lt;-- HIN of +1 (781) 559 0153 --&gt;
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
==== Modify a Simple Value of an Attribute  ====
  
==== Modify a Simple Value of an Attribute ====
+
This example changes the Simple Value '''+1 (781) 559 0153''' to '''+1 234 56789''' on the Attribute '''+phone''' on the Entity '''=paul'''.
  
This example changes the Simple Value '''+1 (781) 559 0153''' to '''+1 234 56789''' on the Attribute '''+phone''' on the Entity '''=paul'''.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next(); // value is "+1 (781) 559 0153"
 
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next(); // value is "+1 (781) 559 0153"
 
value.setData("+1 234 56789");
 
value.setData("+1 234 56789");
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 
+
*Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)  
* Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)
+
*After sending the message, the XDI CP re-calculates the HIN of the value, in order to be able to refer to it later
* After sending the message, the XDI CP re-calculates the HIN of the value, in order to be able to refer to it later
+
 
+
Message sent by the [[XDI Context Provider]]:
+
  
<pre>
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
=sender
+
<pre>=sender
 
   $mod
 
   $mod
 
       /
 
       /
Line 453: Line 391:
 
             +phone
 
             +phone
 
               /
 
               /
                   $value$hash$sha256!$!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca <-- HIN of +1 (781) 559 0153 -->
+
                   $value$hash$sha$256!$!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca &lt;-- HIN of +1 (781) 559 0153 --&gt;
 
                     $value
 
                     $value
 
                         "+1 234 56789"
 
                         "+1 234 56789"
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
==== Add a Simple Value to an Attribute  ====
  
==== Add a Simple Value to an Attribute ====
+
This example adds the Simple Value '''+1 987 65432''' to the Attribute '''+phone''' on the Entity '''=paul'''.
  
This example adds the Simple Value '''+1 987 65432''' to the Attribute '''+phone''' on the Entity '''=paul'''.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
 
ISimpleAttrValue value = attribute.addSimpleValue(ITypedValue.STRING_TYPE_URI, "+1 987 65432");
 
ISimpleAttrValue value = attribute.addSimpleValue(ITypedValue.STRING_TYPE_URI, "+1 987 65432");
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 +
*Before sending the message, the XDI CP calculates the HIN of the value
  
* Before sending the message, the XDI CP calculates the HIN of the value
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
 
+
<pre>=sender
Message sent by the [[XDI Context Provider]]:
+
 
+
<pre>
+
=sender
+
 
   $add
 
   $add
 
       /
 
       /
Line 484: Line 416:
 
             +phone
 
             +phone
 
               /
 
               /
                   $value$hash$sha256!bb4d1ce368e89f0f5c4bfb867cd4b0437eadfa7aa559f9b49bf359bc5903a282 <-- HIN of +1 987 65432 -->
+
                   $value$hash$sha$256!bb4d1ce368e89f0f5c4bfb867cd4b0437eadfa7aa559f9b49bf359bc5903a282 &lt;-- HIN of +1 987 65432 --&gt;
 
                     $value
 
                     $value
 
                         "+1 987 65432"
 
                         "+1 987 65432"
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
=== Complex Values  ===
  
=== Complex Values ===
+
==== Remove a Complex Value from an Attribute  ====
  
==== Remove a Complex Value from an Attribute ====
+
This example removes a Complex Value from the Attribute '''+address''' on the Entity '''=paul'''.
  
This example removes a Complex Value from the Attribute '''+address''' on the Entity '''=paul'''.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next(); // second value
 
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next(); // second value
 
value.remove();
 
value.remove();
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 +
*Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)
  
* Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
 
+
<pre>=sender
Message sent by the [[XDI Context Provider]]:
+
 
+
<pre>
+
=sender
+
 
   $del
 
   $del
 
       /
 
       /
Line 518: Line 444:
 
             +address
 
             +address
 
               /
 
               /
                   $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715 <-- HIN of a complex value -->
+
                   $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715 &lt;-- HIN of a complex value --&gt;
</pre>
+
</pre>  
 
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
 
+
==== Add a Complex Value to an Attribute (Example 1) ====
+
  
This example adds a Complex Value to the Attribute '''+address''' on the Entity '''=paul'''. The Complex Value has four Attributes.
+
==== Add a Complex Value to an Attribute (Example 1)  ====
  
[[IdAS]] calls:
+
This example adds a Complex Value to the Attribute '''+address''' on the Entity '''=paul'''. The Complex Value has four Attributes.
  
<pre>
+
[[IdAS]] calls:
IEntity entity = context.getEntity("=paul");
+
<pre>IEntity entity = context.getEntity("=paul");
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IComplexAttrValue value = attribute.addComplexValue(URI.create(BasicComplexValue.ATTR_VALUE_TYPE_URI_STR)));
 
IComplexAttrValue value = attribute.addComplexValue(URI.create(BasicComplexValue.ATTR_VALUE_TYPE_URI_STR)));
Line 542: Line 465:
 
subAttributeZip.addSimpleValue(ITypedValue.STRING_TYPE_URI, "02494");
 
subAttributeZip.addSimpleValue(ITypedValue.STRING_TYPE_URI, "02494");
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 +
*Before sending the message, the XDI CP calculates the HIN of the values, in order to be able to refer to them later
  
* Before sending the message, the XDI CP calculates the HIN of the values, in order to be able to refer to them later
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
 
+
<pre>=sender
Message sent by the [[XDI Context Provider]]:
+
 
+
<pre>
+
=sender
+
 
   $add
 
   $add
 
       /
 
       /
Line 555: Line 475:
 
             +address
 
             +address
 
               /
 
               /
                   $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
+
                   $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
 
                     +city
 
                     +city
 
                         "Needham"
 
                         "Needham"
Line 564: Line 484:
 
                     +zip
 
                     +zip
 
                         "02494"
 
                         "02494"
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
==== Add a Complex Value to an Attribute (Example 2) ====
  
==== Add a Complex Value to an Attribute (Example 2) ====
+
This example adds a Complex Value to the Attribute '''+address''' on the Entity '''=paul'''. The Complex Value has two Attributes.
  
This example adds a Complex Value to the Attribute '''+address''' on the Entity '''=paul'''. The Complex Value has two Attributes.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IComplexAttrValue value = attribute.addComplexValue(URI.create(BasicComplexValue.ATTR_VALUE_TYPE_URI_STR)));
 
IComplexAttrValue value = attribute.addComplexValue(URI.create(BasicComplexValue.ATTR_VALUE_TYPE_URI_STR)));
Line 584: Line 501:
 
subAttributeCountr.addSimpleValue(ITypedValue.STRING_TYPE_URI, "USA");
 
subAttributeCountr.addSimpleValue(ITypedValue.STRING_TYPE_URI, "USA");
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 
+
*Before sending the message, the XDI CP calculates the HIN of the values, in order to be able to refer to them later
* Before sending the message, the XDI CP calculates the HIN of the values, in order to be able to refer to them later
+
 
+
Message sent by the [[XDI Context Provider]]:
+
  
<pre>
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
=sender
+
<pre>=sender
 
   $add
 
   $add
 
       /
 
       /
Line 597: Line 511:
 
             +address
 
             +address
 
               /
 
               /
                   $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
+
                   $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
 
                     +line  
 
                     +line  
 
                         /
 
                         /
                           $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
+
                           $value$hash$sha$256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
 
                               $value
 
                               $value
 
                                 "Needham, Massachusetts 02494"
 
                                 "Needham, Massachusetts 02494"
                           $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
+
                           $value$hash$sha$256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
 
                               $value
 
                               $value
 
                                 "56 Kearney Rd"
 
                                 "56 Kearney Rd"
 
                     +country
 
                     +country
 
                         "USA"
 
                         "USA"
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
==== Modify a Simple Value of a Complex Value (Example 1) ====
  
==== Modify a Simple Value of a Complex Value (Example 1) ====
+
This example changes the Simple Value '''MA''' to '''Massachusetts''' on the Attribute '''+state''' on the second Value of the Attribute '''+address''' on the Entity '''=paul'''.
  
This example changes the Simple Value '''MA''' to '''Massachusetts''' on the Attribute '''+state''' on the second Value of the Attribute '''+address''' on the Entity '''=paul'''.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IComplexAttrValue value = (IComplexAttrValue) attribute.getValues().next().next(); // second value of +address
 
IComplexAttrValue value = (IComplexAttrValue) attribute.getValues().next().next(); // second value of +address
Line 626: Line 537:
 
value.setData("Massachusetts");
 
value.setData("Massachusetts");
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 +
*Before sending the message, the XDI CP calculates the HIN of the values (if it does not know them already)
 +
*After sending the message, the XDI CP re-calculates the HIN of the values, in order to be able to refer to them later
  
* Before sending the message, the XDI CP calculates the HIN of the values (if it does not know them already)
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
* After sending the message, the XDI CP re-calculates the HIN of the values, in order to be able to refer to them later
+
<pre>=sender
 
+
Message sent by the [[XDI Context Provider]]:
+
 
+
<pre>
+
=sender
+
 
   $mod
 
   $mod
 
       /
 
       /
Line 640: Line 548:
 
             +address
 
             +address
 
               /
 
               /
                   $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715 <-- HIN of second value of +address -->
+
                   $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715 &lt;-- HIN of second value of +address --&gt;
 
                     +state
 
                     +state
                         /
+
                         "Massachusetts"
                          $value$hash$sha256!f0055891f09fff4839b344a4af5e0482696cab0e0bf307455661ba4056c787ee <-- HIN of MA -->
+
</pre>  
                              $value
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
                                "Massachusetts"
+
</pre>
+
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
==== Modify a Simple Value of a Complex Value (Example 2) ====
  
==== Modify a Simple Value of a Complex Value (Example 2) ====
+
This example changes the Simple Value '''Needham, Massachusetts 02494''' to '''Needham, MA 02494''' on the Attribute '''+line''' on the third Value of the Attribute '''+address''' on the Entity '''=paul'''.
  
This example changes the Simple Value '''Needham, Massachusetts 02494''' to '''Needham, MA 02494''' on the Attribute '''+line''' on the third Value of the Attribute '''+address''' on the Entity '''=paul'''.
+
[[IdAS]] calls:  
 
+
<pre>IEntity entity = context.getEntity("=paul");
[[IdAS]] calls:
+
 
+
<pre>
+
IEntity entity = context.getEntity("=paul");
+
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
 
IComplexAttrValue value = (IComplexAttrValue) attribute.getValues().next().next().next(); // third value of +address
 
IComplexAttrValue value = (IComplexAttrValue) attribute.getValues().next().next().next(); // third value of +address
Line 664: Line 566:
 
value.setData("Needham, MA 02494");
 
value.setData("Needham, MA 02494");
 
context.applyUpdates();
 
context.applyUpdates();
</pre>
+
</pre>  
 
+
*Before sending the message, the XDI CP calculates the HIN of the values (if it does not know them already)  
* Before sending the message, the XDI CP calculates the HIN of the values (if it does not know them already)
+
*After sending the message, the XDI CP re-calculates the HIN of the values, in order to be able to refer to them later
* After sending the message, the XDI CP re-calculates the HIN of the values, in order to be able to refer to them later
+
 
+
Message sent by the [[XDI Context Provider]]:
+
  
<pre>
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:
=sender
+
<pre>=sender
 
   $mod
 
   $mod
 
       /
 
       /
Line 678: Line 577:
 
             +address
 
             +address
 
               /
 
               /
                   $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324 <-- HIN of third value of +address -->
+
                   $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324 &lt;-- HIN of third value of +address --&gt;
 
                     +line
 
                     +line
 
                         /
 
                         /
                           $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32 <-- HIN of Needham, Massachusetts 02494 -->
+
                           $value$hash$sha$256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32 &lt;-- HIN of Needham, Massachusetts 02494 --&gt;
 
                               $value
 
                               $value
 
                                 "Needham, MA 02494"
 
                                 "Needham, MA 02494"
</pre>
+
</pre>  
 +
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint: (none)
  
Reply from the [[XDI Engine]] / native XDI endpoint: (none)
+
== Miscellaneous  ==
  
== Miscellaneous ==
+
=== Get the schema of the Context  ===
  
=== Get the schema of the Context ===
+
[[IdAS]] calls:
 +
<pre>String schema = IContext.getSchema();
 +
</pre>
 +
Schema support in IdAS maps to XDI dictionary statements.
  
[[IdAS]] calls:
+
'''TODO'''
  
<pre>
+
=== Get Context Relations and Context Correlations  ===
String schema = IContext.getSchema();
+
</pre>
+
  
Schema support in IdAS maps to XDI dictionary statements.
+
[[IdAS]] calls:
 +
<pre>IContext.getRelationships()
 +
</pre>
 +
'''TODO'''
  
'''TODO'''
+
=== Authentication  ===
  
=== Get Context Relations and Context Correlations ===
+
The Higgins authentication materials needed to open an XDI context are:
  
[[IdAS]] calls:
+
*A Sender XRI (i-name or i-number)
 +
*A Private Key which is used to sign all messages
  
<pre>
+
Example:  
IContext.getRelationships()
+
<pre>=sender
</pre>
+
 
+
'''TODO'''
+
 
+
=== Authentication ===
+
 
+
The Higgins authentication materials needed to open an XDI context are:
+
* A Sender XRI (i-name or i-number)
+
* A Private Key which is used to sign all messages
+
 
+
Example:
+
 
+
<pre>
+
=sender
+
 
$get
 
$get
 
/
 
/
=markus
+
=paul
+(http://www.example.com/name)
+
+address
 
$sig$rsa
 
$sig$rsa
 
"bCbYq6EN26N1hdJTtrjvHw05X+MtNzyFKuyPMoEX/nHxzotTAlGDfHqGuUGMgWIrAtFBkre+bbrUA07gjb6do8kr5OsmOKYvfEi/rxnbEhlEPfISEP5/SWJ8auc+W8E6TOPK2bBTxTrt4+5JGIE4TjiP1IZe9l85rqOmeAY5TLZkFzxGanD01Jf4EbB8qDdNjVsQSZgW0zcqyAdi7/quqTLesxLM9m340doFdHhJxW0cdVLS5CjBU67TR1uDSMEfMpqQhEp8qfQaD/0dUif5Wr5/q+L8nz9BsBQ9tzfFhUSATYMaL1whNNWHEpoO/OGKQPADv/PJbsbN7T3dwyjlBA=="
 
"bCbYq6EN26N1hdJTtrjvHw05X+MtNzyFKuyPMoEX/nHxzotTAlGDfHqGuUGMgWIrAtFBkre+bbrUA07gjb6do8kr5OsmOKYvfEi/rxnbEhlEPfISEP5/SWJ8auc+W8E6TOPK2bBTxTrt4+5JGIE4TjiP1IZe9l85rqOmeAY5TLZkFzxGanD01Jf4EbB8qDdNjVsQSZgW0zcqyAdi7/quqTLesxLM9m340doFdHhJxW0cdVLS5CjBU67TR1uDSMEfMpqQhEp8qfQaD/0dUif5Wr5/q+L8nz9BsBQ9tzfFhUSATYMaL1whNNWHEpoO/OGKQPADv/PJbsbN7T3dwyjlBA=="
</pre>
+
</pre>  
 +
=== Access control  ===
  
=== Access control ===
+
Access control in IdAS maps to XDI link contracts.
  
Access control in IdAS maps to XDI link contracts.
+
'''TODO'''
  
'''TODO'''
+
=== Notifications  ===
  
=== Notifications ===
+
Notification support in IdAS maps to XDI links contracts.
  
Notification support in IdAS maps to XDI links contracts.
+
'''TODO'''
  
'''TODO'''
+
=== Filters  ===
  
=== Filters ===
+
Filter support in IdAS maps to XDI queries.
  
Filter support in IdAS maps to XDI queries.
+
On the OASIS XDI TC there was a proposal for an XDI query language. The idea is simple: You send a $get and replace everything you don't know with $$. So if you want to have all attributes with a name attribute that has a value of "Sergey", you would do:
  
On the OASIS XDI TC there was a proposal for an XDI query language. The idea is simple: You send a $get and replace everything you don't know with $$. So if you want to have all attributes with a name attribute that has a value of "Sergey", you would do:
+
Message sent by the [[Org.eclipse.higgins.idas.cp.xdi|XDI CP]]:  
 
+
<pre>=sender
Message sent by the [[XDI Context Provider]]:  
+
 
+
<pre>
+
=sender
+
 
     $get
 
     $get
 
         /
 
         /
             $$  <-- we don't know the subject -->
+
             $$  &lt;-- we don't know the subject --&gt;
 
                 +(http://www.example.com/name)
 
                 +(http://www.example.com/name)
 
                     /
 
                     /
 
                         $$
 
                         $$
                             +(http://www.example.com/name)
+
                             $value
 
                                 "Sergey"
 
                                 "Sergey"
</pre>
+
</pre>  
 
+
Reply from the [[Org.eclipse.higgins.as|Attribute Service]] / native XDI endpoint:  
Reply from the [[XDI Engine]] / native XDI endpoint:
+
<pre>=sergey    &lt;-- that's what matched the $$ --&gt;
 
+
<pre>
+
=sergey    <-- that's what matched the $$ -->
+
 
     +(http://www.example.com/name)
 
     +(http://www.example.com/name)
 
         /
 
         /
 
             $!11cac773045ffc189fa2e3ed232843d363d019c6
 
             $!11cac773045ffc189fa2e3ed232843d363d019c6
                 +(http://www.example.com/name)
+
                 $value
 
                     "Sergey"
 
                     "Sergey"
</pre>
+
</pre>  
 
+
This can be tested with the [http://graceland.parityinc.net/xdi-querier/XDIQuerier XDI Querier].  
This can be tested with the [http://graceland.parityinc.net/xdi-querier/XDIQuerier XDI Querier].
+
  
== Links ==
+
== Links ==
  
* [http://eclipse.org/higgins Higgins Home]
+
*[http://www.oasis-open.org/committees/download.php/27004/xdi-rdf-model-v8.pdf The XDI RDF Model] is the current OASIS TC proposal for an RDF-based data model and addressing format for XDI. This document includes the proposed XDI RDF schema and a number of examples of XDI documents. (Note that it does not yet include the proposed XDI messaging format, which uses XDI documents as message envelopes for other XDI documents.)  
* [http://www.oasis-open.org/committees/download.php/27004/xdi-rdf-model-v8.pdf The XDI RDF Model] is the current OASIS TC proposal for an RDF-based data model and addressing format for XDI. This document includes the proposed XDI RDF schema and a number of examples of XDI documents. (Note that it does not yet include the proposed XDI messaging format, which uses XDI documents as message envelopes for other XDI documents.)
+
*[http://wiki.oasis-open.org/xdi/ OASIS XDI TC Wiki]  
* [http://wiki.oasis-open.org/xdi/ OASIS XDI TC Wiki]
+
*[http://en.wikipedia.org/wiki/XDI Wikipedia page on XDI]
* [http://en.wikipedia.org/wiki/XDI Wikipedia page on XDI]
+

Latest revision as of 20:24, 9 August 2010

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

Status

  • This document needs to be updated to show a representative Persona Data Model 2.0 data structure instead of the "made up" structure shown in the diagram below.
  • The endpoints are all broken at present (old parityinc, graceland links)

Introduction

This page documents the mapping between the Higgins Context Data Model (which is implemented by IdAS) and XDI. XDI ("XRI Data Interchange") is a data model and protocol for sharing, linking, and synchronizing data over the Internet ("structured web") and other networks using Extensible Resource Identifiers (XRIs). It is being developed by the OASIS XDI Technical Committee.

The Attribute Service exposes an IdAS Context at an XDI endpoint. It processes and applies incoming XDI messages.

The XDI CP implements an IdAS Context by sending XDI messages. These message can be sent either to an XDI endpoint exposed by the Attribute Service or to a native XDI endpoint.

Mapping

Concepts

Since the Higgins Data Model is based on RDF/OWL, and XDI is also based on RDF, the basic mapping is straightforward. However, some attention has to be paid to details.

A Higgins Context can be mapped to an XDI graph using the following rules:

  • An Entity maps to an XDI subject. The XDI subject's XRI is the Entity ID cast to an XRI.
  • An Attribute maps to an XDI predicate. The XDI predicate's XRI is the Attribute ID cast to an XRI.
  • In general, each Value of an Attribute maps to an XDI subject inside an XDI inner graph. The XDI subject's XRI is a HIN (Hash I-Number) calculated from the Value.
    • If the Value is a Simple Value, then the XDI subject in the XDI inner graph has a single XDI predicate with an XDI literal. The XDI predicate's XRI is the the special $value XDI predicate.
    • If the Value is a Complex Value, then the rules for mapping the Attributes of that Complex Value apply recursively, i.e. each Attribute of the Complex Value maps to an XDI predicate.
  • Special case 1: If an Attribute contains only a single Simple Value, then that Attribute does not need an inner graph. Instead the Value maps directly to an XDI literal on the XDI predicate that represents the Attribute.
  • Special case 2: If an Attribute is an Entity Relation, then that Attribute does not need an inner graph. Instead the Values map directly to XDI references on the XDI predicate that represents the Attribute.
  • An Entity Correlation maps to an XDI statement with the special $is XDI predicate
  • The type of an Entity maps to an XDI statement with the special $is$a XDI predicate
  • The type of a Value maps to an XDI statement with the special $is$a XDI predicate

Example

Example Context diagram:

IdAS XDI.png

Example Context description:

  • The Context has three Entities =paul, =sergey and =drummond.
  • =paul has an Attribute +name, which has a single Simple Value :"Paul T.".
  • =paul has an Entity Relation +friend to =sergey and =drummond.
  • =paul has an Attribute +phone, which has two Values:
    • The first Value is a Simple Value: "+1 (617) 513 7924".
    • The second Value is a Simple Value: "+1 (781) 559 0153".
  • =paul has an Attribute +address, which has three Values:
    • The first Value is a Simple Value: "56 Kearney Rd, Needham, Massachusetts 02494, USA".
    • The second Value is a Complex Value. It has four Attributes +street, +city, +state and +zip.
      • The first Attribute has a single Simple Value: "56 Kearney Rd".
      • The second Attribute has a single Simple Value: "Needham".
      • The third Attribute has a single Simple Value: "MA".
      • The fourth Attribute has a single Simple Value: "02494".
    • The third Value is a Complex Value. It has two Attributes +line and +country.
      • The first Attribute has two Values.
        • The first Value is a Simple Value: "56 Kearney Rd".
        • The second Value is a Simple Value: "Needham, Massachusetts 2494".
      • The second Attribute has a single Simple Value: "USA".

Example Context in XDI:

=paul     <-- An Entity -->
   +name     <-- A "Special Case 1" Attribute -->
      "Paul T."     <-- A single Simple Value -->
   +friend     <-- A "Special Case 2" Attribute -->
      =sergey     <-- An Entity Relation Value -->
      =drummond     <-- An Entity Relation Value -->
   +phone     <-- An Attribute with two Values -->
      /
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d     <-- First Value of +phone: A Simple Value -->
            $value
               "+1 (617) 513 7924"
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca     <-- Second Value of +phone: A Simple Value -->
            $value
               "+1 (781) 559 0153"
   +address     <-- An Attribute with three Values -->
      /
         $value$hash$sha$256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c     <-- First Value of +address: A Simple Value -->
            $value
               "56 Kearney Rd, Needham, Massachusetts 02494, USA"
         $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715     <-- Second Value of +address: A Complex Value with four Attributes -->
            +street     <-- A "Special Case 1" Attribute -->
               "56 Kearney Rd"     <-- A single Simple Value -->
            +city     <-- A "Special Case 1" Attribute -->
               "Needham"     <-- A single Simple Value -->
            +state     <-- A "Special Case 1" Attribute -->
               "MA"     <-- A single Simple Value -->
            +zip     <-- A "Special Case 1" Attribute -->
               "02494"     <-- A single Simple Value -->
         $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324     <-- Third Value of +address: A Complex Value with two Attributes -->
            +line     <-- An Attribute with two values -->
               /
                  $value$hash$sha$256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c     <-- First Value of +line: A Simple Value -->
                     $value
                        "56 Kearney Rd"
                  $value$hash$sha$256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32     <-- Second Value of +line: A Simple Value -->
                     $value
                        "Needham, Massachusetts 02494"
            +country     <-- A "Special Case 1" Attribute -->
               "USA"     <-- A single Simple Value -->
=sergey     <-- An Entity -->
=drummond     <-- An Entity -->

Hash I-Numbers for Simple Values

On several occasions in this mapping, it is necessary to refer to individual Simple Values of a multi-valued Attribute. Since Simple Values in Higgins IdAS do not have persistent identifiers, a mechanism called "Hash I-Number" (HIN) is used. A HIN is an i-number that is deterministically calculated from a value, therefore acting as an index of that Value in an XDI inner graph.

This pseudocode can be used to calculate a HIN for a Simple Value:

FUNCTION makeSimpleValueHin(simpleValue)

  String hin = "$value$hash$sha$256" + "!" + hex(sha256(simpleValue.lexical));
  RETURN hin;
END

Examples:

  • "Sergey" becomes $value$hash$sha$256!f3357799ddcf994ae4d759e37d58c29938419f5af9681ae65a6f0f1677b213b7
  • "Markus" becomes $value$hash$sha$256!f00b1896cf1c0569b9bdcfdde4ed948a266bae9707b3567240211efc8ffc06a0
  • "+1 (617) 513 7924" becomes $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
  • "+1 (781) 559 0153" becomes $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca

Hash I-Numbers for Complex Values

Hash I-Numbers are also used to refer to individual Complex Values. Like with Simple Values, HINs for Complex Values are calculated from the Value and can then be used as an index of that Value in an XDI inner graph.

This pseudocode can be used to calculate a HIN for a Complex Value:

FUNCTION makeComplexValueHin(complexValue):

  String hin = "$value$hash$sha$256" + "!" + hex(sha256(makeComplexString(complexValue)));
  RETURN hin;
END

FUNCTION makeComplexValueString(complexValue):

  String buffer = "";
  Set attributeIds;  # a set of strings representing the attribute ids of this complex value

  FOR EACH attribute IN complexValue.attributes

    attibuteIds.push(attrIdToXri(attribute.attributeId))
  END

  FOR EACH attributeId IN sort(attributeIds)

    buffer += attributeId + ' ';
    Set simpleValuesStrings;  # a set of strings representing the simple values of this complex value
    Set complexValuesStrings;  # a set of strings representing the complex values of this complex value

    Attribute attribute = complexValue.getAttribute(attributeId)

    FOR EACH value IN attribute.values

      IF value.isSimple THEN
        simpleValuesStrings.push('"' + value.lexical + '"' + ' ')
      ELSE IF value.isComplex THEN
        complexValuesStrings.push(makeComplexValueString(value) + ' ')
      END IF
    END FOR

    buffer += concat(sort(simpleValuesStrings));
    buffer += concat(sort(complexValuesStrings));
  END FOR

  RETURN buffer;
END

Examples:

  • For the second Value of +address,
    • the result of the makeComplexValueString() function is +city{space}"Needham"{space}+state{space}"MA"{space}+street{space}"56 Kearney Rd"{space}+zip{space}"02494"{space}
    • the result of the makeComplexValueHin() function is $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
  • For the third Value of +address,
    • the result of the makeComplexString() function is +country{space}"USA"{space}+line{space}"56 Kearney Rd"{space}"Needham, Massachusetts 02494"{space}
    • the result of the makeComplexHin() function is $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324

Test endpoints

The following XDI endpoints are available for testing:

IdAS Attribute Service

Native XDI Endpoints

Operations

Using IdAS, a Higgins context can be opened, and operations can be performed on it. The equivalent in XDI is XDI messages (which contain XDI operations).

All XDI examples are in the X3 Simple serialization format. See X3Format for more information about X3 serialization formats.

Entities

List all Entities

This example gets all Entities in the Context.

IdAS calls:

Iterator<Entity> entities = context.getEntities(null);

Message sent by the XDI CP:

=sender
	$get

Reply from the Attribute Service / native XDI endpoint:

=paul
=sergey
=drummond

Get one Entity from the Context

This example gets the Entity =paul in the Context.

IdAS calls:

IEntity entity = context.getEntity("=paul");

Message sent by the XDI CP:

=sender
   $get$a$xsd$boolean
      /
         =paul

Reply from the Attribute Service / native XDI endpoint:

$true

Remove an Entity from the Context

This example removes Entity =paul from the Context.

IdAS calls:

IEntity entity = context.getEntity("=paul");
entity.remove();
context.applyUpdates();

Message sent by the XDI CP:

=sender
   $del
      /
         =paul

Reply from the Attribute Service / native XDI endpoint: (none)

Attributes

List all Attributes from an Entity

This example gets all Attributes of the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
Iterator<IAttribute> attributes = entity.getAttributes();

Message sent by the XDI CP:

=sender
   $get
      /
         =paul
  • After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later

Reply from the Attribute Service / native XDI endpoint:

=paul
   +name
   +friend
   +phone
   +address

Get one Attribute from an Entity

This example gets the Attribute +phone of the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));

Message sent by the XDI CP:

=sender
   $get$a$xsd$boolean
      /
         =paul
            +phone
  • After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later

Reply from the Attribute Service / native XDI endpoint:

$true

Remove an Attribute from an Entity

This example removes the Attribute +phone from the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
attribute.remove();
context.applyUpdates();

Message sent by the XDI CP:

=sender
   $del
      /
         =paul
            +phone

Reply from the Attribute Service / native XDI endpoint: (none)

Values

List all Values from an Attribute

This example gets all Values of the Attribute +phone on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
Iterator<IAttributeValue> values = attribute.getValues();

Message sent by the XDI CP:

=sender
   $get
      /
         =paul
            +phone
  • After sending the message, the XDI CP remembers the HINs of the individual values, in order to be able to refer to them later

Reply from the Attribute Service / native XDI endpoint:

=paul
   +phone
      /
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d     <-- First Value of +phone: A Simple Value -->
            $value
               "+1 (617) 513 7924"
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca     <-- Second Value of +phone: A Simple Value -->
            $value
               "+1 (781) 559 0153"


Simple Values

Remove a Simple Value from an Attribute

This example removes the Simple Value +1 (781) 559 0153 from the Attribute +phone on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next();	// value is "+1 (781) 559 0153"
value.remove();
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)

Message sent by the XDI CP:

=sender
   $del
      /
         =paul
            +phone
               /
                  $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca	<-- HIN of +1 (781) 559 0153 -->

Reply from the Attribute Service / native XDI endpoint: (none)

Modify a Simple Value of an Attribute

This example changes the Simple Value +1 (781) 559 0153 to +1 234 56789 on the Attribute +phone on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next();	// value is "+1 (781) 559 0153"
value.setData("+1 234 56789");
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)
  • After sending the message, the XDI CP re-calculates the HIN of the value, in order to be able to refer to it later

Message sent by the XDI CP:

=sender
   $mod
      /
         =paul
            +phone
               /
                  $value$hash$sha$256!$!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca	<-- HIN of +1 (781) 559 0153 -->
                     $value
                        "+1 234 56789"

Reply from the Attribute Service / native XDI endpoint: (none)

Add a Simple Value to an Attribute

This example adds the Simple Value +1 987 65432 to the Attribute +phone on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+phone"));
ISimpleAttrValue value = attribute.addSimpleValue(ITypedValue.STRING_TYPE_URI, "+1 987 65432");
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the value

Message sent by the XDI CP:

=sender
   $add
      /
         =paul
            +phone
               /
                  $value$hash$sha$256!bb4d1ce368e89f0f5c4bfb867cd4b0437eadfa7aa559f9b49bf359bc5903a282	<-- HIN of +1 987 65432 -->
                     $value
                        "+1 987 65432"

Reply from the Attribute Service / native XDI endpoint: (none)

Complex Values

Remove a Complex Value from an Attribute

This example removes a Complex Value from the Attribute +address on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
ISimpleAttrValue value = (ISimpleAttrValue) attribute.getValues().next().next();	// second value
value.remove();
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the value (if it does not know it already)

Message sent by the XDI CP:

=sender
   $del
      /
         =paul
            +address
               /
                  $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715	<-- HIN of a complex value -->

Reply from the Attribute Service / native XDI endpoint: (none)

Add a Complex Value to an Attribute (Example 1)

This example adds a Complex Value to the Attribute +address on the Entity =paul. The Complex Value has four Attributes.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
IComplexAttrValue value = attribute.addComplexValue(URI.create(BasicComplexValue.ATTR_VALUE_TYPE_URI_STR)));
IAttribute subAttributeCity = value.addAttribute(URI.create("xri://+city"));
IAttribute subAttributeState = value.addAttribute(URI.create("xri://+state"));
IAttribute subAttributeStreet = value.addAttribute(URI.create("xri://+street"));
IAttribute subAttributeZip = value.addAttribute(URI.create("xri://+zip"));
subAttributeCity.addSimpleValue(ITypedValue.STRING_TYPE_URI, "Needham");
subAttributeState.addSimpleValue(ITypedValue.STRING_TYPE_URI, "MA");
subAttributeStreet.addSimpleValue(ITypedValue.STRING_TYPE_URI, "56 Kearney Rd");
subAttributeZip.addSimpleValue(ITypedValue.STRING_TYPE_URI, "02494");
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the values, in order to be able to refer to them later

Message sent by the XDI CP:

=sender
   $add
      /
         =paul
            +address
               /
                  $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
                     +city
                        "Needham"
                     +street
                        "56 Kearney Rd"
                     +state
                        "MA"
                     +zip
                        "02494"

Reply from the Attribute Service / native XDI endpoint: (none)

Add a Complex Value to an Attribute (Example 2)

This example adds a Complex Value to the Attribute +address on the Entity =paul. The Complex Value has two Attributes.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
IComplexAttrValue value = attribute.addComplexValue(URI.create(BasicComplexValue.ATTR_VALUE_TYPE_URI_STR)));
IAttribute subAttributeLine = value.addAttribute(URI.create("xri://+line"));
IAttribute subAttributeCountry = value.addAttribute(URI.create("xri://+country"));
subAttributeLine.addSimpleValue(ITypedValue.STRING_TYPE_URI, "Needham, Massachusetts 02494");
subAttributeLine.addSimpleValue(ITypedValue.STRING_TYPE_URI, "56 Kearney Rd");
subAttributeCountr.addSimpleValue(ITypedValue.STRING_TYPE_URI, "USA");
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the values, in order to be able to refer to them later

Message sent by the XDI CP:

=sender
   $add
      /
         =paul
            +address
               /
                  $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
                     +line 
                        /
                           $value$hash$sha$256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
                              $value
                                 "Needham, Massachusetts 02494"
                           $value$hash$sha$256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
                              $value
                                 "56 Kearney Rd"
                     +country
                        "USA"

Reply from the Attribute Service / native XDI endpoint: (none)

Modify a Simple Value of a Complex Value (Example 1)

This example changes the Simple Value MA to Massachusetts on the Attribute +state on the second Value of the Attribute +address on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
IComplexAttrValue value = (IComplexAttrValue) attribute.getValues().next().next();	// second value of +address
IAttribute subAttribute = value.getAttribute(URI.create("xri://+state"));
ISimpleAttrValue subValue = (ISimpleAttrValue) subAttribute.getValues().next();		// value is "MA"
value.setData("Massachusetts");
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the values (if it does not know them already)
  • After sending the message, the XDI CP re-calculates the HIN of the values, in order to be able to refer to them later

Message sent by the XDI CP:

=sender
   $mod
      /
         =paul
            +address
               /
                  $value$hash$sha$256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715	<-- HIN of second value of +address -->
                     +state
                        "Massachusetts"

Reply from the Attribute Service / native XDI endpoint: (none)

Modify a Simple Value of a Complex Value (Example 2)

This example changes the Simple Value Needham, Massachusetts 02494 to Needham, MA 02494 on the Attribute +line on the third Value of the Attribute +address on the Entity =paul.

IdAS calls:

IEntity entity = context.getEntity("=paul");
IAttribute attribute = entity.getAttribute(URI.create("xri://+address"));
IComplexAttrValue value = (IComplexAttrValue) attribute.getValues().next().next().next();	// third value of +address
IAttribute subAttribute = value.getAttribute(URI.create("xri://+line"));
ISimpleAttrValue subValue = (ISimpleAttrValue) subAttribute.getValues().next();		// value is "Needham, Massachusetts 02494"
value.setData("Needham, MA 02494");
context.applyUpdates();
  • Before sending the message, the XDI CP calculates the HIN of the values (if it does not know them already)
  • After sending the message, the XDI CP re-calculates the HIN of the values, in order to be able to refer to them later

Message sent by the XDI CP:

=sender
   $mod
      /
         =paul
            +address
               /
                  $value$hash$sha$256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324	<-- HIN of third value of +address -->
                     +line
                        /
                           $value$hash$sha$256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32 <-- HIN of Needham, Massachusetts 02494 -->
                              $value
                                 "Needham, MA 02494"

Reply from the Attribute Service / native XDI endpoint: (none)

Miscellaneous

Get the schema of the Context

IdAS calls:

String schema = IContext.getSchema();

Schema support in IdAS maps to XDI dictionary statements.

TODO

Get Context Relations and Context Correlations

IdAS calls:

IContext.getRelationships() 

TODO

Authentication

The Higgins authentication materials needed to open an XDI context are:

  • A Sender XRI (i-name or i-number)
  • A Private Key which is used to sign all messages

Example:

=sender
	$get
		/
			=paul
				+address
	$sig$rsa
		"bCbYq6EN26N1hdJTtrjvHw05X+MtNzyFKuyPMoEX/nHxzotTAlGDfHqGuUGMgWIrAtFBkre+bbrUA07gjb6do8kr5OsmOKYvfEi/rxnbEhlEPfISEP5/SWJ8auc+W8E6TOPK2bBTxTrt4+5JGIE4TjiP1IZe9l85rqOmeAY5TLZkFzxGanD01Jf4EbB8qDdNjVsQSZgW0zcqyAdi7/quqTLesxLM9m340doFdHhJxW0cdVLS5CjBU67TR1uDSMEfMpqQhEp8qfQaD/0dUif5Wr5/q+L8nz9BsBQ9tzfFhUSATYMaL1whNNWHEpoO/OGKQPADv/PJbsbN7T3dwyjlBA=="

Access control

Access control in IdAS maps to XDI link contracts.

TODO

Notifications

Notification support in IdAS maps to XDI links contracts.

TODO

Filters

Filter support in IdAS maps to XDI queries.

On the OASIS XDI TC there was a proposal for an XDI query language. The idea is simple: You send a $get and replace everything you don't know with $$. So if you want to have all attributes with a name attribute that has a value of "Sergey", you would do:

Message sent by the XDI CP:

=sender
    $get
        /
            $$  <-- we don't know the subject -->
                +(http://www.example.com/name)
                    /
                        $$
                            $value
                                "Sergey"

Reply from the Attribute Service / native XDI endpoint:

=sergey    <-- that's what matched the $$ -->
    +(http://www.example.com/name)
        /
            $!11cac773045ffc189fa2e3ed232843d363d019c6
                $value
                    "Sergey"

This can be tested with the XDI Querier.

Links

  • The XDI RDF Model is the current OASIS TC proposal for an RDF-based data model and addressing format for XDI. This document includes the proposed XDI RDF schema and a number of examples of XDI documents. (Note that it does not yet include the proposed XDI messaging format, which uses XDI documents as message envelopes for other XDI documents.)
  • OASIS XDI TC Wiki
  • Wikipedia page on XDI

Back to the top