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

Difference between revisions of "Org.eclipse.higgins.idas.udi"

(New page: == Intro == This page outlines a proposal on how to implement UDI Resolution in Higgins. See http://www.parity.com/udi for details on UDIs. A UDI is a string (URI, XRI, Cool URI or a...)
 
 
(34 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== Intro ==
+
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}
 +
[[Image:Higgins_logo_76Wx100H.jpg|right]]
  
−
This page outlines a proposal on how to implement [[UDI]] Resolution in Higgins. See http://www.parity.com/udi for details on UDIs.
+
This page describes the '''higgins.idas.udi''' component which implements [[UDI]] Resolution in Higgins. See http://www.azigo.com/company/dev/udi/ for details on UDIs.
  
−
A UDI is a string (URI, XRI, Cool URI or anything else) that somehow can be dereferenced to a Context, Entity or Attribute.
+
A UDI is a string (URI, XRI, Linked Data URI or anything else) that somehow can be dereferenced to a [[Context]], [[Entity]] or [[Attribute]].
  
−
The proposal is to create a new project called idas.udi, which will contain the functionality described on this page.
+
==Javadoc==
 +
* ''Javadoc'': [http://download.eclipse.org/technology/higgins/downloads/idas.udi/lastNightlyBuild/javadoc/index.html Javadoc]
  
−
== Implementation Details ==
+
== Service ==
  
 
=== Context UDIs ===
 
=== Context UDIs ===
  
−
The following interfaces and classes are provided to support the resolution of Context UDIs to fully instantiated and configured IContexts.
+
The following interfaces are provided to support the concept of Context UDIs:
  
 
<source lang="java">
 
<source lang="java">
  
−
/*
+
/**
−
  * A Context UDI is defined to be any string that can be used to obtain Context UDI Metadata.
+
  * A Context UDI is an abstract, absolute pointer to an IdAS Context.
 
  */
 
  */
−
 
+
public interface IContextUDI extends Serializable, Comparable {
−
interface IContextUDI {
+
  
 
public IContextUDIMetadata getContextUDIMetadata();
 
public IContextUDIMetadata getContextUDIMetadata();
 
}
 
}
  
−
/*
+
/**
−
  * Context UDI Metadata is defined to be everything needed to instantiate an IContext:
+
  * When you resolve a Context UDI, you get Context UDI Metadata.
−
  *   - required: one or more Context Types
+
* This is:
−
  *   - optional: the schema of the Context
+
  * - A list of one or more Context Types
−
  *   - optional: a configuration map of the Context
+
  * - (optional) The type of Authentication Materials required to open the Context
 +
  * - (optional) Configuration map for the Context
 
  */
 
  */
 +
public interface IContextUDIMetadata {
  
−
interface IContextMetadata {
+
public String[] getTypes() throws IdASException;
−
 
+
public String[] getAuthNMaterialsTypes() throws IdASException;
−
public String[] getTypes();
+
public String getAuthNMaterials() throws IdASException;
−
public String getSchema();
+
public Map getConfiguration() throws IdASException;
−
public Map getConfiguration();
+
 
}
 
}
  
Line 42: Line 44:
 
=== Entity UDIs ===
 
=== Entity UDIs ===
  
−
The following interfaces and classes are provided to support the resolution of Entity UDIs to fully instantiated and configured IEntitys.
+
The following interfaces are provided to support the concept of Entity UDIs:
  
 
<source lang="java">
 
<source lang="java">
  
−
/*
+
/**
−
  * An Entity UDI (also called Resource UDI) is defined to be any string that can be used to obtain Entity UDI Metadata.
+
  * An Entity UDI is an abstract, absolute pointer to an IdAS Entity.
 
  */
 
  */
−
 
+
public interface IEntityUDI extends Serializable, Comparable {
−
interface IEntityUDI {
+
  
 
public IEntityUDIMetadata getEntityUDIMetadata();
 
public IEntityUDIMetadata getEntityUDIMetadata();
 
}
 
}
  
−
/*
+
/**
−
  * Entity UDI Metadata is defined to be everything needed to instantiate an IEntity:
+
  * When you resolve an Entity UDI, you get Entity UDI Metadata.
−
  *   - required: Context UDI Metadata of the Context the Entity is in
+
* This is:
−
  *   - required: A relative Entity ID which identifies the Entity within its Context
+
  * - Context UDI Metadata of the Context the Entity is in
 +
  * - The Entity ID of the Entity
 
  */
 
  */
 +
public interface IEntityUDIMetadata {
  
−
interface IEntityUDIMetadata {
+
public IContextUDIMetadata getContextUDIMetadata() throws IdASException;
−
 
+
public String getEntityID() throws IdASException;
−
public IContextUDIMetadata getContextUDIMetadata();
+
−
public String getEntityID();
+
 
}
 
}
  
Line 71: Line 72:
 
=== Attribute UDIs ===
 
=== Attribute UDIs ===
  
−
The following interfaces and classes are provided to support the resolution of Attribute UDIs to fully instantiated and configured IAttributes.
+
The following interfaces are provided to support the concept of Attribute UDIs:
  
 
<source lang="java">
 
<source lang="java">
  
−
/*
+
/**
−
  * An Attribute UDI is defined to be any string that can be used to obtain Attribute Metadata.
+
  * An Attribute UDI is an abstract, absolute pointer to an IdAS Attribute.
 
  */
 
  */
 +
public interface IAttributeUDI extends Serializable, Comparable {
  
−
interface IAttributeUDI {
+
public IAttributeUDIMetadata getAttributeUDIMetadata();
−
 
+
−
public IAttributeMetadata getAttributeMetadata();
+
 
}
 
}
  
−
/*
+
/**
−
  * Attribute Metadata is defined to be everything needed to instantiate an IAttribute:
+
  * When you resolve an Attribute UDI, you get Attribbute UDI Metadata.
−
  *   - required: Entity Metadata of the Entity the Attribute belongs to
+
* This is:
−
  *   - required: A relative Attribute ID which identifies the Attribute on its Entity
+
  * - Entity UDI Metadata of the Entity the Attribute belongs to
 +
  * - The Attribute ID of the Attribute
 
  */
 
  */
 +
public interface IAttributeUDIMetadata {
  
−
interface IAttributeMetadata {
+
public IEntityUDIMetadata getEntityUDIMetadata() throws IdASException;
−
 
+
public URI getAttributeID() throws IdASException;
−
public IEntityMetadata getEntityMetadata();
+
−
public URI getAttributeID();
+
 
}
 
}
  
Line 100: Line 100:
 
=== UDIResolver ===
 
=== UDIResolver ===
  
−
The UDIResolver is the most important piece of the idas.udi project. It is a singleton class that you use to parse and resolve UDIs.
+
The UDIResolver is the central piece of the idas.udi project. It is a singleton class that you use to parse and resolve UDIs.
  
−
It is agnostic of any specific UDI implementation. Instead, it uses a list of IUDIFactorys (see next section) for parsing UDIs.
+
It is agnostic of any specific UDI implementation. Instead, it uses a list of IUDIFactory's (see next section) for parsing UDIs.
  
 
<source lang="java">
 
<source lang="java">
  
−
public class UDIResolver implements IConfigurableComponent, IConfigurableComponentFactory {
+
public class UDIResolver implements IConfigurableComponent {
  
 
private static UDIResolver impl = null;
 
private static UDIResolver impl = null;
Line 121: Line 121:
 
if (impl == null) impl = new UDIResolver();
 
if (impl == null) impl = new UDIResolver();
 
return(impl);
 
return(impl);
−
}
 
−
 
−
public IConfigurableComponent getNewInstance() {
 
−
 
−
return(new IdASRegistry());
 
−
}
 
−
 
−
public IConfigurableComponent getSingletonInstance() {
 
−
 
−
return(getInstance());
 
 
}
 
}
  
 
/**
 
/**
−
* Register the UDIFactorys from the configuration
+
* Register the IUDIFactorys from the configuration
 
*/
 
*/
−
public void configure(Map mapGlobalSettings, String strComponentName, Map mapComponentSettings) throws Exception {
+
public void configure(Map mapGlobalSettings, String strComponentName, Map mapComponentSettings) throws Exception { ... }
−
 
+
−
List udiFactoryInstances = (List) mapComponentSettings.get("UDIFactoryInstancesList");
+
−
 
+
−
this.udiFactoryList.clear();
+
−
 
+
−
for (Iterator i = udiFactoryInstances.iterator(); i.hasNext(); ) {
+
−
 
+
−
String udiFactoryInstanceName = (String) i.next();
+
−
 
+
−
// Look for the context factory first in the component settings, then, if not there, in the global settings.
+
−
 
+
−
IUDIFactory udiFactory;
+
−
 
+
−
udiFactory = (IUDIFactory) mapComponentSettings.get(udiFactoryInstanceName);
+
−
if (udiFactory == null) udiFactory = (IUDIFactory) mapGlobalSettings.get(udiFactoryInstanceName);
+
−
 
+
−
this.udiFactoryList.add(udiFactory);
+
−
}
+
−
}
+
  
 
/**
 
/**
Line 161: Line 132:
 
* until one succeeds.
 
* until one succeeds.
 
*/
 
*/
−
public IContextUDI parseContextUDI(String contextUDIStr) throws IdASException {
+
public IContextUDI parseContextUDI(String contextUDIStr) throws IdASException { ... }
  
−
IContextUDI contextUDI = null;
+
/**
 +
* Parse a string into an IEntityUDI by trying all registered IUDIFactorys
 +
* until one succeeds.
 +
*/
 +
public IEntityUDI parseEntityUDI(String entityUDIStr) throws IdASException { ... }
  
−
for (Iterator i = this.udiFactoryList.iterator(); i.hasNext(); ) {
+
/**
 +
* Parse a string into an IAttributeUDI by trying all registered IUDIFactorys
 +
* until one succeeds.
 +
*/
 +
public IAttributeUDI parseAttributeUDI(String attributeUDIStr) throws IdASException { ... }
  
−
IUDIFactory udiFactory = (IUDIFactory) i.next();
+
/**
 +
* Resolve an IContextUDI to an IContext by retrieving the IContextUDIMetadata
 +
*/
 +
public IContext resolve(IContextUDI contextUDI, Object authentication) throws IdASException { ... }
  
−
contextUDI = udiFactory.parseContextUDI(contextUDIStr);
+
/**
−
if (contextUDI != null) break;
+
* Resolve an IEntityUDI to an IEntity by retrieving the IEntityUDIMetadata
−
}
+
*/
−
 
+
public IEntity resolve(IEntityUDI entityUDI, Object authentication) throws IdASException { ... }
−
return(contextUDI);
+
−
}
+
  
 
/**
 
/**
−
* Parse a string into an IEntityUDI by trying all registered IUDIFactorys
+
* Resolve an IAttributeUDI to an IAttribute by retrieving the IAttributeUDIMetadata
−
* until one succeeds.
+
 
*/
 
*/
−
public IEntityUDI parseEntityUDI(String entityUDIStr) throws IdASException {
+
public IAttribute resolve(IAttributeUDI attributeUDI, Object authentication) throws IdASException { ... }
 +
}
  
−
IEntityUDI entityUDI = null;
+
</source>
  
−
for (Iterator i = this.udiFactoryList.iterator(); i.hasNext(); ) {
+
=== IUDIFactory ===
  
−
IUDIFactory udiFactory = (IUDIFactory) i.next();
+
A UDI Factory is one specific implementation of the generic UDI concept. It can parse strings into IContextUDIs, IEntityUDIs and IAttributeUDIs. The UDIResolver singleton class keeps a list of IUDIFactory's. This list can be configured via the [[Configuration API]].
  
−
entityUDI = udiFactory.parseEntityUDI(entityUDIStr);
+
The IUDIFactory interface is simple:
−
if (entityUDI != null) break;
+
−
}
+
  
−
return(entityUDI);
+
<source lang="java">
−
}
+
  
−
/**
+
public interface IUDIFactory {
−
* Parse a string into an IAttributeUDI by trying all registered IUDIFactorys
+
−
* until one succeeds.
+
−
*/
+
−
public IAttributeUDI parseAttributeUDI(String attributeUDIStr) throws IdASException {
+
  
−
IAttributeUDI attributeUDI = null;
+
public IContextUDI parseContextUDI(String contextUDI);
 +
public IEntityUDI parseEntityUDI(String entityUDI);
 +
public IAttributeUDI parseAttributeUDI(String attributeUDI);
 +
}
  
−
for (Iterator i = this.udiFactoryList.iterator(); i.hasNext(); ) {
+
</source>
  
−
IUDIFactory udiFactory = (IUDIFactory) i.next();
+
The following IUDIFactory implementations are included in Higgins:
 +
* XDIUDIFactory: Can parse XRIs into Context UDIs, Entity UDIs and Attribute UDIs.
 +
* URIUDIFactory: Can parse URIs without fragments into Context UDIs and Entity UDIs.
 +
* HashURIUDIFactory: Can parse URIs with fragments into Context UDIs and Entity UDIs.
 +
* ConfUDIFactory: This makes it possible to also use the Context IDs stored in IdASRegistry as Context UDIs.
 +
* PDSUDIFactory: Can parse '''sync://''' UDIs to enable the [[Personal Data Store]].
  
−
attributeUDI = udiFactory.parseAttributeUDI(attributeUDIStr);
+
Because of this configurable IUDIFactory mechanism, the UDI concept is extensible. New kinds of UDIs (pointers to Contexts, Entities and Attributes) can be realized by simply writing another IUDIFactory implementation.
−
if (attributeUDI != null) break;
+
−
}
+
  
−
return(attributeUDI);
+
The following is an example configuration XML file for UDIResolver that shows a possible default list of IUDIFactory's:
−
}
+
  
−
/**
+
<source lang="xml">
−
* Resolve an IContextUDI to an IContext by retrieving the IContextUDIMetadata
+
−
*/
+
−
public IContext resolve(IContextUDI contextUDI, Object authentication) throws IdASException {
+
  
−
IContextUDIMetadata contextUDIMetadata = contextUDI.getContextMetadata();
+
<Configuration
 +
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 +
xmlns="http://higgins.eclipse.org/Configuration"
 +
xmlns:htf="http://higgins.eclipse.org/Configuration"
 +
xsd:schemaLocation="http://higgins.eclipse.org/Configuration Configuration.xsd">
 +
 +
<!--  The setting handlers are classes that consume Setting elements where the Type matches and generate an object of the Class -->
 +
<SettingHandlers>
 +
<SettingHandler Type="htf:map" Class="java.util.Map" Handler="org.eclipse.higgins.configuration.xml.MapHandler"/>
 +
<SettingHandler Type="htf:list" Class="java.util.List" Handler="org.eclipse.higgins.configuration.xml.ListHandler"/>
 +
<SettingHandler Type="htf:string" Class="java.lang.String" Handler="org.eclipse.higgins.configuration.xml.StringHandler"/>
 +
<SettingHandler Type="htf:boolean" Class="java.lang.Boolean" Handler="org.eclipse.higgins.configuration.xml.BooleanHandler"/>
 +
<SettingHandler Type="htf:classsingleton" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.ClassSingletonHandler"/>
 +
<SettingHandler Type="htf:classinstance" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.ClassInstanceHandler"/>
 +
</SettingHandlers>
 +
 +
<Setting Name="DeploymentConfiguration" Type="htf:map">
  
−
return(this.resolve(contextUDIMetadata, authentication));
+
<Setting Name="ComponentSettings" Type="htf:map">
−
}
+
  
−
/**
+
<Setting Name="XRIUDIFactory" Type="htf:map">
−
* Resolve an IEntityUDI to an IEntity by retrieving the IEntityUDIMetadata
+
<Setting Name="Resolver" Type="htf:map">
−
*/
+
<Setting Name="MaxFollowRedirects" Type="htf:string">5</Setting>
−
public IEntity resolve(IEntityUDI entityUDI, Object authentication) throws IdASException {
+
<Setting Name="MaxFollowRefs" Type="htf:string">10</Setting>
 +
<Setting Name="MaxRequests" Type="htf:string">15</Setting>
 +
<Setting Name="MaxTotalBytes" Type="htf:string">10485760</Setting>
 +
<Setting Name="MaxBytesPerRequest" Type="htf:string">1048576</Setting>
 +
<Setting Name="AtAuthority" Type="htf:string"><![CDATA[<XRD xmlns="xri://$xrd*($v*2.0)" xmlns:xrd="xri://$xrd*($v*2.0)"><Status cid="verified" ceid="off" code="100" /><CanonicalID>@</CanonicalID><Service><Type>xri://$res*auth*($v*2.0)</Type><MediaType match="default" select="false" /><URI priority="1">https://at.xri.net/</URI><URI priority="2">http://at.xri.net/</URI></Service> </XRD>]]></Setting>
 +
<Setting Name="EqualsAuthority" Type="htf:string"><![CDATA[<XRD xmlns="xri://$xrd*($v*2.0)" xmlns:xrd="xri://$xrd*($v*2.0)"><Status cid="verified" ceid="off" code="100" /><CanonicalID>=</CanonicalID><Service><Type>xri://$res*auth*($v*2.0)</Type><MediaType match="default" select="false" /><URI priority="1">https://equal.xri.net/</URI><URI priority="2">http://equal.xri.net/</URI></Service> </XRD>]]></Setting>
 +
<Setting Name="BangAuthority" Type="htf:string"><![CDATA[<XRD xmlns="xri://$xrd*($v*2.0)" xmlns:xrd="xri://$xrd*($v*2.0)"><Status cid="verified" ceid="off" code="100" /><CanonicalID>!</CanonicalID><Service><Type>xri://$res*auth*($v*2.0)</Type><MediaType match="default" select="false" /><URI priority="1">https://bang.xri.net/</URI><URI priority="2">http://bang.xri.net/</URI></Service> </XRD>]]></Setting>
 +
</Setting>
 +
<Setting Name="ResolverFlags" Type="htf:map">
 +
<Setting Name="https" Type="htf:boolean">false</Setting>
 +
<Setting Name="saml" Type="htf:boolean">false</Setting>
 +
<Setting Name="cid" Type="htf:boolean">true</Setting>
 +
<Setting Name="refs" Type="htf:boolean">true</Setting>
 +
</Setting>
 +
</Setting>
 +
<Setting Name="URIUDIFactory" Type="htf:map" />
 +
<Setting Name="HashURIUDIFactory" Type="htf:map" />
 +
<Setting Name="ConfUDIFactory" Type="htf:map" />
  
−
IEntityUDIMetadata entityUDIMetadata = entityUDI.getEntityUDIMetadata();
+
<Setting Name="UDIResolver" Type="htf:map">
 +
<Setting Name="UDIFactoryInstancesList" Type="htf:list">
 +
<Setting Name="XRIUDIFactory" Type="htf:string">XRIUDIFactory</Setting>
 +
<Setting Name="URIUDIFactory" Type="htf:string">URIUDIFactory</Setting>
 +
<Setting Name="HashURIUDIFactory" Type="htf:string">HashURIUDIFactory</Setting>
 +
<Setting Name="ConfUDIFactory" Type="htf:string">ConfUDIFactory</Setting>
 +
</Setting>
 +
</Setting>
  
−
return(this.resolve(entityUDIMetadata, authentication));
+
<Setting Name="IdASRegistry" Type="htf:map">
−
}
+
<Setting Name="ContextFactoryInstancesList" Type="htf:list">
 +
<Setting Name="JNDIContextFactory" Type="htf:map">
 +
<Setting Name="Instance" Type="htf:string">JNDIContextFactory</Setting>
 +
<Setting Name="ContextTypes" Type="htf:list">
 +
<Setting Name="ContextType1" Type="htf:string">($context)*(+ldap)</Setting>
 +
</Setting>
 +
</Setting>
 +
<Setting Name="RDFContextFactory" Type="htf:map">
 +
<Setting Name="Instance" Type="htf:string">RDFContextFactory</Setting>
 +
<Setting Name="ContextTypes" Type="htf:list">
 +
<Setting Name="ContextType1" Type="htf:string">$context$mime*application*rdf.xml</Setting>
 +
</Setting>
 +
</Setting>
 +
</Setting>
 +
 +
<Setting Name="ContextIdsList" Type="htf:list">
 +
<Setting Name="localContext" Type="htf:map">
 +
<Setting Name="ContextId" Type="htf:string">localContext</Setting>
 +
<Setting Name="ContextTypes" Type="htf:list">
 +
<Setting Name="HigginsContextType" Type="htf:string">$context+ldap</Setting>
 +
</Setting>
 +
<Setting Name="Connection" Type="htf:map">
 +
<Setting Name="ConnectionType" Type="htf:string">LDAP</Setting>
 +
<Setting Name="AddressList" Type="htf:list">
 +
<Setting Name="Address" Type="htf:string">ldap://rh158.sohosmart.net:7389</Setting>
 +
</Setting>
 +
<Setting Name="jndiProvider" Type="htf:string">com.sun.jndi.ldap.LdapCtxFactory</Setting>
 +
</Setting>
 +
<Setting Name="env" Type="htf:map">
 +
<Setting Name="java.naming.security.authentication" Type="htf:string">simple</Setting>
 +
</Setting>
 +
</Setting>
 +
</Setting>
  
−
/**
+
</Setting>
−
* Resolve an IAttributeUDI to an IAttribute by retrieving the IAttributeUDIMetadata
+
−
*/
+
−
public IAttribute resolve(IAttributeUDI attributeUDI, Object authentication) throws IdASException {
+
  
−
IAttributeUDIMetadata attributeUDIMetadata = attributeUDI.getAttributeUDIMetadata();
+
</Setting>
  
−
return(this.resolve(attributeUDIMetadata, authentication));
+
<Setting Name="XRIUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.xri.XRIUDIFactory</Setting>
−
}
+
<Setting Name="URIUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.uri.URIUDIFactory</Setting>
 +
<Setting Name="HashURIUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.hashuri.HashURIUDIFactory</Setting>
 +
<Setting Name="ConfUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.conf.ConfUDIFactory</Setting>
  
−
/**
+
<Setting Name="UDIResolver" Type="htf:classsingleton">org.eclipse.higgins.idas.udi.UDIResolver</Setting>
−
* With the IContextUDIMetadata, we have everything we need to instantiate the IContext.
+
−
*/
+
−
private IContext resolve(IContextUDIMetadata contextUDIMetadata, Object authentication) throws IdASException {
+
  
−
IdASRegistry idasRegistry = IdASRegistry.getInstance();
+
<Setting Name="JNDIContextFactory" Type="htf:classinstance">org.eclipse.higgins.idas.cp.jndi.JNDIContextFactory</Setting>
 +
<Setting Name="RDFContextFactory" Type="htf:classinstance">org.eclipse.higgins.idas.cp.rdf.RDFContextFactory</Setting>
  
−
String[] types = contextUDIMetadata.getTypes();
+
<Setting Name="IdASRegistry" Type="htf:classsingleton">org.eclipse.higgins.idas.registry.IdASRegistry</Setting>
−
Map configuration = contextUDIMetadata.getConfiguration();
+
  
−
IContextFactory contextFactory = idasRegistry.getContextFactory(types);
+
</Setting>
 +
 +
</Configuration>
  
−
IContext context = contextFactory.createContext(configuration);
+
</source>
−
context.open(authentication);
+
  
−
return(context);
+
== Example usage ==
−
}
+
  
−
/**
+
Here is some example code that contains three examples of how you can start with an [[Entity UDI]] and end up with a fully instantiated [[Entity]]:
−
* With the IEntityUDIMetadata, we have everything we need to instantiate the IContext and the IEntity.
+
−
*/
+
−
private IEntity resolve(IEntityUDIMetadata entityUDIMetadata, Object authentication) throws IdASException {
+
  
−
IContextUDIMetadata contextUDIMetadata = entityUDIMetadata.getContextUDIMetadata();
+
<source lang="java">
−
String entityID = entityUDIMetadata.getEntityID();
+
  
−
IContext context = this.resolve(contextUDIMetadata, authentication);
+
import org.eclipse.higgins.configuration.xml.ConfigurationHandler;
−
IEntity entity = context.getEntity(entityID);
+
import org.eclipse.higgins.idas.api.IEntity;
 +
import org.eclipse.higgins.idas.udi.IEntityUDI;
 +
import org.eclipse.higgins.idas.udi.UDIResolver;
  
−
return(entity);
+
ConfigurationHandler handler = new ConfigurationHandler();
−
}
+
  
−
/**
+
handler.setConfigurationBase(".");
−
* With the IAttributeUDIMetadata, we have everything we need to instantiate the IContext, the IEntity, and the IAttribute.
+
handler.setFileName("test.xml");
−
*/
+
handler.configure(null);
−
private IAttribute resolve(IAttributeUDIMetadata attributeUDIMetadata, Object authentication) throws IdASException {
+
  
−
IEntityUDIMetadata entityUDIMetadata = attributeUDIMetadata.getEntityUDIMetadata();
+
UDIResolver resolver = (UDIResolver) handler.getSettings().get("UDIResolver");
−
URI attributeID = attributeUDIMetadata.getAttributeID();
+
  
−
IEntity entity = this.resolve(entityUDIMetadata, authentication);
+
// Example 1: Entity UDI in XRI form
−
IAttribute attribute = entity.getAttribute(attributeID);
+
  
−
return(attribute);
+
IEntityUDI entityUDI1 = resolver.parseEntityUDI("@parity*contexts/($context)*(+ldap)*(+poc)//uid%3Dmarkus,ou%3Didentities,dc%3Dhiggins,dc%3Declipse,dc%3Dorg");
−
}
+
Object authnMaterials1 = /* ... */;
−
}
+
  
−
</source>
+
IEntity entity1 = resolver.resolve(entityUDI1, authnMaterials1);
  
−
=== IUDIFactory ===
+
// Example 2: Entity UDI in URI form (Linked Data "303" Cool URI):
  
−
A UDI Factory is one specific implementation of the generic UDI concept. It can parse strings into IContextUDIs, IEntityUDIs and IAttributeUDIs. The UDIResolver singleton class keeps a list of IUDIFactorys. This list can be configured via the [[Configuration API]].
+
IEntityUDI entityUDI2 = resolver.parseEntityUDI("http://www.acme.com/id/alice");
 +
Object authnMaterials2 = /* ... */;
  
−
The IUDIFactory interface is simple:
+
IEntity entity2 = resolver.resolve(entityUDI2, authnMaterials2);
  
−
<source lang="java">
+
// Example 3: Entity UDI using a Context from the local Configuration file
  
−
public interface IUDIFactory {
+
IEntityUDI entityUDI3 = resolver.parseEntityUDI("localContext/uid=markus,ou=identities,dc=higgins,dc=eclipse,dc=org");
 +
Object authnMaterials2 = /* ... */;
  
−
public IContextUDI parseContextUDI(String contextUDI);
+
IEntity entity3 = resolver.resolve(entityUDI3, authnMaterials3);
−
public IEntityUDI parseEntityUDI(String entityUDI);
+
−
public IAttributeUDI parseAttributeUDI(String attributeUDI);
+
−
}
+
  
 
</source>
 
</source>
  
−
At least the following IUDIFactory implementations will come out of the box:
+
The only difference between the examples is that different IUDIFactory implementations are used internally by the UDIResolver.
−
* XDIUDIFactory: Can parse XRIs into Context UDIs, Entity UDIs and Attribute UDIs
+
−
* URIUDIFactory: Can parse URIs (both XRDS URIs and Semantic Web Cool URIs) into Context UDIs and Entity UDIs
+
−
 
+
−
Because of this configurable IUDIFactory mechanism, the UDI concept is extensible. New kinds of UDIs (pointers to Contexts, Entities and Attributes) can be invented by simply writing another IUDIFactory implementation.
+
  
 
== Q&A ==
 
== Q&A ==
Line 322: Line 352:
 
The IxxxUDI interface represents the UDI itself. The IxxxUDIMetadata interface provides all the information needed to instantiate the object the UDI points to. The reason why the two interfaces are separate is that an Entity UDI (IEntityUDI) does NOT necessarily have to contain within itself a Context UDI, but it DOES have to provide Context UDI Metadata for the Context the Entity is in. Similarly, an Attribute UDI (IAttributeUDI) does NOT necessarily have to contain within itself an Entity UDI, but it DOES have to provide Entity UDI Metadata for the Entity the Attribute belongs to.
 
The IxxxUDI interface represents the UDI itself. The IxxxUDIMetadata interface provides all the information needed to instantiate the object the UDI points to. The reason why the two interfaces are separate is that an Entity UDI (IEntityUDI) does NOT necessarily have to contain within itself a Context UDI, but it DOES have to provide Context UDI Metadata for the Context the Entity is in. Similarly, an Attribute UDI (IAttributeUDI) does NOT necessarily have to contain within itself an Entity UDI, but it DOES have to provide Entity UDI Metadata for the Entity the Attribute belongs to.
  
−
* '''How does this relate to [[Context_Discovery_Components_Without_XRDS]] and [[Higgins_Configuration_Management]], i.e. the ability to use Context IDs from the Configuration API?'''
+
* '''How does this relate to [[Context_Discovery_Components_Without_XRDS]] and [[Higgins_Configuration_Management]], i.e. the ability to configure Context IDs via the Configuration API?'''
−
 
+
The current idea is that Context IDs from the Configuration API are considered one flavor of Context UDIs, i.e. you are able to parse and resolve them with the UDIResolver class. However, the idas.udi project is not required, if all you need is read/write Context IDs in your configuration file.  
−
Although Context IDs from the Configuration API COULD be considered one flavor of Context UDI, the current idea is to keep the two mechanisms completely separate. This means that if all you need is read/write the Context IDs in your configuration file, then idas.registry makes you totally happy and you don't need this "new, fancy UDI stuff". On the other hand, if you want the more powerful UDI concept and for example use XRIs to point to Entities or Attributes, then you use idas.udi, which in turn doesn't touch the Context IDs in your configuration file.
+
  
−
== Implications on existing components and concepts ==
+
== Relation to IdASRegistry ==
  
−
=== Context Types ===
+
[[IdAS UDI Resolution]] is a way of discovering Contexts, Entities and Attributes from a UDI. It uses [[IdASRegistry]] to look up a suitable [[Context Provider]] based on the discovered [[Context Types]].
  
−
The concept of [[Context Type]]s is not changed by the introduction of UDIs. Context Types are still used to look up Context Factories from the IdASRegistry.
+
Therefore, '''idas.udi''' depends on '''idas.registry'''. The converse is not true, i.e. '''idas.registry''' does not depend on '''idas.udi'''.
  
−
=== IdASRegistry ===
+
== See Also ==
 +
* http://www.azigo.com/company/dev/udi/
 +
* [[IdAS 1.1 Package]]
 +
* [http://wiki.eclipse.org/Components_1.X#IdAS IdAS Components]--lists sub-projects (including .idas.udi and as well as projects for available context providers
  
−
Some functionality that is currently in IdASRegistry will be moved to the new idas.udi project, e.g.:
+
[[Category:Higgins Components]]
−
* XRIs and URIs as Context IDs will becomes types of Context UDIs.
+
−
* Eventually, it may make sense to remove the IContextId interface and ContextIdFactory class.
+

Latest revision as of 16:58, 10 November 2010

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

Higgins logo 76Wx100H.jpg

This page describes the higgins.idas.udi component which implements UDI Resolution in Higgins. See http://www.azigo.com/company/dev/udi/ for details on UDIs.

A UDI is a string (URI, XRI, Linked Data URI or anything else) that somehow can be dereferenced to a Context, Entity or Attribute.

Javadoc

Service

Context UDIs

The following interfaces are provided to support the concept of Context UDIs: 

/**
 * A Context UDI is an abstract, absolute pointer to an IdAS Context.
 */
public interface IContextUDI extends Serializable, Comparable {
 
	public IContextUDIMetadata getContextUDIMetadata();
}
 
/**
 * When you resolve a Context UDI, you get Context UDI Metadata.
 * This is:
 * - A list of one or more Context Types
 * - (optional) The type of Authentication Materials required to open the Context
 * - (optional) Configuration map for the Context
 */
public interface IContextUDIMetadata {
 
	public String[] getTypes() throws IdASException;
	public String[] getAuthNMaterialsTypes() throws IdASException;
	public String getAuthNMaterials() throws IdASException;
	public Map getConfiguration() throws IdASException;
}

Entity UDIs

The following interfaces are provided to support the concept of Entity UDIs: 

/**
 * An Entity UDI is an abstract, absolute pointer to an IdAS Entity.
 */
public interface IEntityUDI extends Serializable, Comparable {
 
	public IEntityUDIMetadata getEntityUDIMetadata();
}
 
/**
 * When you resolve an Entity UDI, you get Entity UDI Metadata.
 * This is:
 * - Context UDI Metadata of the Context the Entity is in
 * - The Entity ID of the Entity
 */
public interface IEntityUDIMetadata {
 
	public IContextUDIMetadata getContextUDIMetadata() throws IdASException;
	public String getEntityID() throws IdASException;
}

Attribute UDIs

The following interfaces are provided to support the concept of Attribute UDIs: 

/**
 * An Attribute UDI is an abstract, absolute pointer to an IdAS Attribute.
 */
public interface IAttributeUDI extends Serializable, Comparable {
 
	public IAttributeUDIMetadata getAttributeUDIMetadata();
}
 
/**
 * When you resolve an Attribute UDI, you get Attribbute UDI Metadata.
 * This is:
 * - Entity UDI Metadata of the Entity the Attribute belongs to
 * - The Attribute ID of the Attribute
 */
public interface IAttributeUDIMetadata {
 
	public IEntityUDIMetadata getEntityUDIMetadata() throws IdASException;
	public URI getAttributeID() throws IdASException;
}

UDIResolver

The UDIResolver is the central piece of the idas.udi project. It is a singleton class that you use to parse and resolve UDIs.

It is agnostic of any specific UDI implementation. Instead, it uses a list of IUDIFactory's (see next section) for parsing UDIs. 

public class UDIResolver implements IConfigurableComponent {
 
	private static UDIResolver impl = null;
 
	private List udiFactoryList;
 
	public UDIResolver() {
 
		this.udiFactoryList = new ArrayList();
	}
 
	public static synchronized UDIResolver getInstance() {
 
		if (impl == null) impl = new UDIResolver();
		return(impl);
	}
 
	/**
	 * Register the IUDIFactorys from the configuration
	 */
	public void configure(Map mapGlobalSettings, String strComponentName, Map mapComponentSettings) throws Exception { ... }
 
	/**
	 * Parse a string into an IContextUDI by trying all registered IUDIFactorys
	 * until one succeeds.
	 */
	public IContextUDI parseContextUDI(String contextUDIStr) throws IdASException { ... }
 
	/**
	 * Parse a string into an IEntityUDI by trying all registered IUDIFactorys
	 * until one succeeds.
	 */
	public IEntityUDI parseEntityUDI(String entityUDIStr) throws IdASException { ... }
 
	/**
	 * Parse a string into an IAttributeUDI by trying all registered IUDIFactorys
	 * until one succeeds.
	 */
	public IAttributeUDI parseAttributeUDI(String attributeUDIStr) throws IdASException { ... }
 
	/**
	 * Resolve an IContextUDI to an IContext by retrieving the IContextUDIMetadata
	 */
	public IContext resolve(IContextUDI contextUDI, Object authentication) throws IdASException { ... }
 
	/**
	 * Resolve an IEntityUDI to an IEntity by retrieving the IEntityUDIMetadata
	 */
	public IEntity resolve(IEntityUDI entityUDI, Object authentication) throws IdASException { ... }
 
	/**
	 * Resolve an IAttributeUDI to an IAttribute by retrieving the IAttributeUDIMetadata
	 */
	public IAttribute resolve(IAttributeUDI attributeUDI, Object authentication) throws IdASException { ... }
}

IUDIFactory

A UDI Factory is one specific implementation of the generic UDI concept. It can parse strings into IContextUDIs, IEntityUDIs and IAttributeUDIs. The UDIResolver singleton class keeps a list of IUDIFactory's. This list can be configured via the Configuration API.

The IUDIFactory interface is simple: 

public interface IUDIFactory {
 
	public IContextUDI parseContextUDI(String contextUDI);
	public IEntityUDI parseEntityUDI(String entityUDI);
	public IAttributeUDI parseAttributeUDI(String attributeUDI);
}

The following IUDIFactory implementations are included in Higgins:

  • XDIUDIFactory: Can parse XRIs into Context UDIs, Entity UDIs and Attribute UDIs.
  • URIUDIFactory: Can parse URIs without fragments into Context UDIs and Entity UDIs.
  • HashURIUDIFactory: Can parse URIs with fragments into Context UDIs and Entity UDIs.
  • ConfUDIFactory: This makes it possible to also use the Context IDs stored in IdASRegistry as Context UDIs.
  • PDSUDIFactory: Can parse sync:// UDIs to enable the Personal Data Store.

Because of this configurable IUDIFactory mechanism, the UDI concept is extensible. New kinds of UDIs (pointers to Contexts, Entities and Attributes) can be realized by simply writing another IUDIFactory implementation.

The following is an example configuration XML file for UDIResolver that shows a possible default list of IUDIFactory's: 

<Configuration
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns="http://higgins.eclipse.org/Configuration"
	xmlns:htf="http://higgins.eclipse.org/Configuration"
	xsd:schemaLocation="http://higgins.eclipse.org/Configuration Configuration.xsd">
 
	<!--  The setting handlers are classes that consume Setting elements where the Type matches and generate an object of the Class -->
	<SettingHandlers>
		<SettingHandler Type="htf:map" Class="java.util.Map" Handler="org.eclipse.higgins.configuration.xml.MapHandler"/>
		<SettingHandler Type="htf:list" Class="java.util.List" Handler="org.eclipse.higgins.configuration.xml.ListHandler"/>
		<SettingHandler Type="htf:string" Class="java.lang.String" Handler="org.eclipse.higgins.configuration.xml.StringHandler"/>
		<SettingHandler Type="htf:boolean" Class="java.lang.Boolean" Handler="org.eclipse.higgins.configuration.xml.BooleanHandler"/>
		<SettingHandler Type="htf:classsingleton" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.ClassSingletonHandler"/>
		<SettingHandler Type="htf:classinstance" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.ClassInstanceHandler"/>
	</SettingHandlers>
 
	<Setting Name="DeploymentConfiguration" Type="htf:map">
 
		<Setting Name="ComponentSettings" Type="htf:map">
 
			<Setting Name="XRIUDIFactory" Type="htf:map">
				<Setting Name="Resolver" Type="htf:map">
					<Setting Name="MaxFollowRedirects" Type="htf:string">5</Setting>
					<Setting Name="MaxFollowRefs" Type="htf:string">10</Setting>
					<Setting Name="MaxRequests" Type="htf:string">15</Setting>
					<Setting Name="MaxTotalBytes" Type="htf:string">10485760</Setting>
					<Setting Name="MaxBytesPerRequest" Type="htf:string">1048576</Setting>
					<Setting Name="AtAuthority" Type="htf:string"><![CDATA[<XRD xmlns="xri://$xrd*($v*2.0)" xmlns:xrd="xri://$xrd*($v*2.0)"><Status cid="verified" ceid="off" code="100" /><CanonicalID>@</CanonicalID><Service><Type>xri://$res*auth*($v*2.0)</Type><MediaType match="default" select="false" /><URI priority="1">https://at.xri.net/</URI><URI priority="2">http://at.xri.net/</URI></Service> </XRD>]]></Setting>
					<Setting Name="EqualsAuthority" Type="htf:string"><![CDATA[<XRD xmlns="xri://$xrd*($v*2.0)" xmlns:xrd="xri://$xrd*($v*2.0)"><Status cid="verified" ceid="off" code="100" /><CanonicalID>=</CanonicalID><Service><Type>xri://$res*auth*($v*2.0)</Type><MediaType match="default" select="false" /><URI priority="1">https://equal.xri.net/</URI><URI priority="2">http://equal.xri.net/</URI></Service> </XRD>]]></Setting>
					<Setting Name="BangAuthority" Type="htf:string"><![CDATA[<XRD xmlns="xri://$xrd*($v*2.0)" xmlns:xrd="xri://$xrd*($v*2.0)"><Status cid="verified" ceid="off" code="100" /><CanonicalID>!</CanonicalID><Service><Type>xri://$res*auth*($v*2.0)</Type><MediaType match="default" select="false" /><URI priority="1">https://bang.xri.net/</URI><URI priority="2">http://bang.xri.net/</URI></Service> </XRD>]]></Setting>
				</Setting>
				<Setting Name="ResolverFlags" Type="htf:map">
					<Setting Name="https" Type="htf:boolean">false</Setting>
					<Setting Name="saml" Type="htf:boolean">false</Setting>
					<Setting Name="cid" Type="htf:boolean">true</Setting>
					<Setting Name="refs" Type="htf:boolean">true</Setting>
				</Setting>
			</Setting>
			<Setting Name="URIUDIFactory" Type="htf:map" />
			<Setting Name="HashURIUDIFactory" Type="htf:map" />
			<Setting Name="ConfUDIFactory" Type="htf:map" />
 
			<Setting Name="UDIResolver" Type="htf:map">
				<Setting Name="UDIFactoryInstancesList" Type="htf:list">
					<Setting Name="XRIUDIFactory" Type="htf:string">XRIUDIFactory</Setting>
					<Setting Name="URIUDIFactory" Type="htf:string">URIUDIFactory</Setting>
					<Setting Name="HashURIUDIFactory" Type="htf:string">HashURIUDIFactory</Setting>
					<Setting Name="ConfUDIFactory" Type="htf:string">ConfUDIFactory</Setting>
				</Setting>
			</Setting>
 
			<Setting Name="IdASRegistry" Type="htf:map">
				<Setting Name="ContextFactoryInstancesList" Type="htf:list">
					<Setting Name="JNDIContextFactory" Type="htf:map">
						<Setting Name="Instance" Type="htf:string">JNDIContextFactory</Setting>
						<Setting Name="ContextTypes" Type="htf:list">
							<Setting Name="ContextType1" Type="htf:string">($context)*(+ldap)</Setting>
						</Setting>
					</Setting>
					<Setting Name="RDFContextFactory" Type="htf:map">
						<Setting Name="Instance" Type="htf:string">RDFContextFactory</Setting>
						<Setting Name="ContextTypes" Type="htf:list">
							<Setting Name="ContextType1" Type="htf:string">$context$mime*application*rdf.xml</Setting>
						</Setting>
					</Setting>
				</Setting>
 
				<Setting Name="ContextIdsList" Type="htf:list">
					<Setting Name="localContext" Type="htf:map">
						<Setting Name="ContextId" Type="htf:string">localContext</Setting>
						<Setting Name="ContextTypes" Type="htf:list">
							<Setting Name="HigginsContextType" Type="htf:string">$context+ldap</Setting>
						</Setting>
						<Setting Name="Connection" Type="htf:map">
							<Setting Name="ConnectionType" Type="htf:string">LDAP</Setting>
							<Setting Name="AddressList" Type="htf:list">
								<Setting Name="Address" Type="htf:string">ldap://rh158.sohosmart.net:7389</Setting>
							</Setting>
							<Setting Name="jndiProvider" Type="htf:string">com.sun.jndi.ldap.LdapCtxFactory</Setting>
						</Setting>
						<Setting Name="env" Type="htf:map">
							<Setting Name="java.naming.security.authentication" Type="htf:string">simple</Setting>
						</Setting>
					</Setting>
				</Setting>
 
			</Setting>
 
		</Setting>
 
		<Setting Name="XRIUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.xri.XRIUDIFactory</Setting>
		<Setting Name="URIUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.uri.URIUDIFactory</Setting>
		<Setting Name="HashURIUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.hashuri.HashURIUDIFactory</Setting>
		<Setting Name="ConfUDIFactory" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.conf.ConfUDIFactory</Setting>
 
		<Setting Name="UDIResolver" Type="htf:classsingleton">org.eclipse.higgins.idas.udi.UDIResolver</Setting>
 
		<Setting Name="JNDIContextFactory" Type="htf:classinstance">org.eclipse.higgins.idas.cp.jndi.JNDIContextFactory</Setting>
		<Setting Name="RDFContextFactory" Type="htf:classinstance">org.eclipse.higgins.idas.cp.rdf.RDFContextFactory</Setting>
 
		<Setting Name="IdASRegistry" Type="htf:classsingleton">org.eclipse.higgins.idas.registry.IdASRegistry</Setting>
 
	</Setting>
 
</Configuration>

Example usage

Here is some example code that contains three examples of how you can start with an Entity UDI and end up with a fully instantiated Entity: 

import org.eclipse.higgins.configuration.xml.ConfigurationHandler;
import org.eclipse.higgins.idas.api.IEntity;
import org.eclipse.higgins.idas.udi.IEntityUDI;
import org.eclipse.higgins.idas.udi.UDIResolver;
 
ConfigurationHandler handler = new ConfigurationHandler();
 
handler.setConfigurationBase(".");
handler.setFileName("test.xml");
handler.configure(null);
 
UDIResolver resolver = (UDIResolver) handler.getSettings().get("UDIResolver");
 
// Example 1: Entity UDI in XRI form
 
IEntityUDI entityUDI1 = resolver.parseEntityUDI("@parity*contexts/($context)*(+ldap)*(+poc)//uid%3Dmarkus,ou%3Didentities,dc%3Dhiggins,dc%3Declipse,dc%3Dorg");
Object authnMaterials1 = /* ... */;
 
IEntity entity1 = resolver.resolve(entityUDI1, authnMaterials1);
 
// Example 2: Entity UDI in URI form (Linked Data "303" Cool URI):
 
IEntityUDI entityUDI2 = resolver.parseEntityUDI("http://www.acme.com/id/alice");
Object authnMaterials2 = /* ... */;
 
IEntity entity2 = resolver.resolve(entityUDI2, authnMaterials2);
 
// Example 3: Entity UDI using a Context from the local Configuration file
 
IEntityUDI entityUDI3 = resolver.parseEntityUDI("localContext/uid=markus,ou=identities,dc=higgins,dc=eclipse,dc=org");
Object authnMaterials2 = /* ... */;
 
IEntity entity3 = resolver.resolve(entityUDI3, authnMaterials3);

The only difference between the examples is that different IUDIFactory implementations are used internally by the UDIResolver.

Q&A

  • Why are there separate IxxxUDI and IxxxUDIMetadata interfaces? Why isn't it enough to have IxxxUDI?

The IxxxUDI interface represents the UDI itself. The IxxxUDIMetadata interface provides all the information needed to instantiate the object the UDI points to. The reason why the two interfaces are separate is that an Entity UDI (IEntityUDI) does NOT necessarily have to contain within itself a Context UDI, but it DOES have to provide Context UDI Metadata for the Context the Entity is in. Similarly, an Attribute UDI (IAttributeUDI) does NOT necessarily have to contain within itself an Entity UDI, but it DOES have to provide Entity UDI Metadata for the Entity the Attribute belongs to.

The current idea is that Context IDs from the Configuration API are considered one flavor of Context UDIs, i.e. you are able to parse and resolve them with the UDIResolver class. However, the idas.udi project is not required, if all you need is read/write Context IDs in your configuration file.

Relation to IdASRegistry

IdAS UDI Resolution is a way of discovering Contexts, Entities and Attributes from a UDI. It uses IdASRegistry to look up a suitable Context Provider based on the discovered Context Types.

Therefore, idas.udi depends on idas.registry. The converse is not true, i.e. idas.registry does not depend on idas.udi.

See Also

Retrieved from "https://wiki.eclipse.org/index.php?title=Org.eclipse.higgins.idas.udi&oldid=227409"

This page was last modified 16:58, 10 November 2010 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top