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 "Org.eclipse.higgins.idas.udi"

Line 11: Line 11:
 
=== Context UDIs ===
 
=== Context UDIs ===
  
The following interfaces 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">
Line 42: Line 42:
 
=== Entity UDIs ===
 
=== Entity UDIs ===
  
The following interfaces 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">
Line 71: Line 71:
 
=== Attribute UDIs ===
 
=== Attribute UDIs ===
  
The following interfaces 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">

Revision as of 05:33, 5 August 2008

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 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.

Implementation Details

Context UDIs

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

/*
 * A Context UDI is defined to be any string that can be used to obtain Context UDI Metadata.
 */
 
interface IContextUDI {
 
	public IContextUDIMetadata getContextUDIMetadata();
}
 
/*
 * Context UDI Metadata is defined to be everything needed to instantiate an IContext:
 *   - required: one or more Context Types
 *   - optional: the schema of the Context
 *   - optional: a configuration map of the Context
 */
 
interface IContextMetadata {
 
	public String[] getTypes();
	public String getSchema();
	public Map getConfiguration();
}

Entity UDIs

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

/*
 * An Entity UDI (also called Resource UDI) is defined to be any string that can be used to obtain Entity UDI Metadata.
 */
 
interface IEntityUDI {
 
	public IEntityUDIMetadata getEntityUDIMetadata();
}
 
/*
 * Entity UDI Metadata is defined to be everything needed to instantiate an IEntity:
 *   - required: Context UDI Metadata of the Context the Entity is in
 *   - required: A relative Entity ID which identifies the Entity within its Context
 */
 
interface IEntityUDIMetadata {
 
	public IContextUDIMetadata getContextUDIMetadata();
	public String getEntityID();
}

Attribute UDIs

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

/*
 * An Attribute UDI is defined to be any string that can be used to obtain Attribute Metadata.
 */
 
interface IAttributeUDI {
 
	public IAttributeMetadata getAttributeMetadata();
}
 
/*
 * Attribute Metadata is defined to be everything needed to instantiate an IAttribute:
 *   - required: Entity Metadata of the Entity the Attribute belongs to
 *   - required: A relative Attribute ID which identifies the Attribute on its Entity
 */
 
interface IAttributeMetadata {
 
	public IEntityMetadata getEntityMetadata();
	public URI getAttributeID();
}

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.

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

public class UDIResolver implements IConfigurableComponent, IConfigurableComponentFactory {
 
	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);
	}
 
	public IConfigurableComponent getNewInstance() {
 
		return(new IdASRegistry());
	}
 
	public IConfigurableComponent getSingletonInstance() {
 
		return(getInstance());
	}
 
	/**
	 * Register the UDIFactorys from the configuration
	 */
	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(); ) {
 
			IUDIFactory udiFactory = (IUDIFactory) i.next();
 
			this.udiFactoryList.add(udiFactory);
		}
	}
 
	/**
	 * Parse a string into an IContextUDI by trying all registered IUDIFactorys
	 * until one succeeds.
	 */
	public IContextUDI parseContextUDI(String contextUDIStr) throws IdASException {
 
		IContextUDI contextUDI = null;
 
		for (Iterator i = this.udiFactoryList.iterator(); i.hasNext(); ) {
 
			IUDIFactory udiFactory = (IUDIFactory) i.next();
 
			contextUDI = udiFactory.parseContextUDI(contextUDIStr);
			if (contextUDI != null) break;
		}
 
		return(contextUDI);
	}
 
	/**
	 * Parse a string into an IEntityUDI by trying all registered IUDIFactorys
	 * until one succeeds.
	 */
	public IEntityUDI parseEntityUDI(String entityUDIStr) throws IdASException {
 
		IEntityUDI entityUDI = null;
 
		for (Iterator i = this.udiFactoryList.iterator(); i.hasNext(); ) {
 
			IUDIFactory udiFactory = (IUDIFactory) i.next();
 
			entityUDI = udiFactory.parseEntityUDI(entityUDIStr);
			if (entityUDI != null) break;
		}
 
		return(entityUDI);
	}
 
	/**
	 * Parse a string into an IAttributeUDI by trying all registered IUDIFactorys
	 * until one succeeds.
	 */
	public IAttributeUDI parseAttributeUDI(String attributeUDIStr) throws IdASException {
 
		IAttributeUDI attributeUDI = null;
 
		for (Iterator i = this.udiFactoryList.iterator(); i.hasNext(); ) {
 
			IUDIFactory udiFactory = (IUDIFactory) i.next();
 
			attributeUDI = udiFactory.parseAttributeUDI(attributeUDIStr);
			if (attributeUDI != null) break;
		}
 
		return(attributeUDI);
	}
 
	/**
	 * Resolve an IContextUDI to an IContext by retrieving the IContextUDIMetadata
	 */
	public IContext resolve(IContextUDI contextUDI, Object authentication) throws IdASException {
 
		IContextUDIMetadata contextUDIMetadata = contextUDI.getContextMetadata();
 
		return(this.resolve(contextUDIMetadata, authentication));
	}
 
	/**
	 * Resolve an IEntityUDI to an IEntity by retrieving the IEntityUDIMetadata
	 */
	public IEntity resolve(IEntityUDI entityUDI, Object authentication) throws IdASException {
 
		IEntityUDIMetadata entityUDIMetadata = entityUDI.getEntityUDIMetadata();
 
		return(this.resolve(entityUDIMetadata, authentication));
	}
 
	/**
	 * Resolve an IAttributeUDI to an IAttribute by retrieving the IAttributeUDIMetadata
	 */
	public IAttribute resolve(IAttributeUDI attributeUDI, Object authentication) throws IdASException {
 
		IAttributeUDIMetadata attributeUDIMetadata = attributeUDI.getAttributeUDIMetadata();
 
		return(this.resolve(attributeUDIMetadata, authentication));
	}
 
	/**
	 * 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();
 
		String[] types = contextUDIMetadata.getTypes();
		Map configuration = contextUDIMetadata.getConfiguration();
 
		IContextFactory contextFactory = idasRegistry.getContextFactory(types);
 
		IContext context = contextFactory.createContext(configuration);
		context.open(authentication);
 
		return(context);
	}
 
	/**
	 * 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();
		String entityID = entityUDIMetadata.getEntityID();
 
		IContext context = this.resolve(contextUDIMetadata, authentication);
		IEntity entity = context.getEntity(entityID);
 
		return(entity);
	}
 
	/**
	 * With the IAttributeUDIMetadata, we have everything we need to instantiate the IContext, the IEntity, and the IAttribute.
	 */
	private IAttribute resolve(IAttributeUDIMetadata attributeUDIMetadata, Object authentication) throws IdASException {
 
		IEntityUDIMetadata entityUDIMetadata = attributeUDIMetadata.getEntityUDIMetadata();
		URI attributeID = attributeUDIMetadata.getAttributeID();
 
		IEntity entity = this.resolve(entityUDIMetadata, authentication);
		IAttribute attribute = entity.getAttribute(attributeID);
 
		return(attribute);
	}
}

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 IUDIFactorys. 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);
}

At least the following IUDIFactory implementations will come out of the box:

  • 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.
  • ConfigurationUDIFactory: This is used to also be able to consider the Context IDs stored in IdASRegistry as Context 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.

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

<Setting Name="UDIResolver" Type="htf:map">
	<Setting Name="UDIFactoryInstancesList" Type="htf:list">
		<Setting Name="UDIFactory1" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.xri.XRIUDIFactory</Setting>
		<Setting Name="UDIFactory2" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.uri.URIUDIFactory</Setting>
		<Setting Name="UDIFactory3" Type="htf:classinstance">org.eclipse.higgins.idas.udi.impl.conf.ConfigurationUDIFactory</Setting>
		<Setting Name="UDIFactory4" Type="htf:classinstance">com.parity.test.MyOwnUDIFactory</Setting>
	</Setting>
</Setting>

Example usage

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

ConfigurationHandler handler = new ConfigurationHandler();
 
handler.setConfigurationBase(".");
handler.setFileName("test.xml");
handler.configure(null);
resolver = (UDIResolver) handler.getSettings().get("UDIResolver");
 
// Example 1: Entity UDI in XRI form
 
IEntityUDI entityUDI1 = resolver.parseEntityUDI("@parity*contexts/=(uid=saba,dc=parityinc,dc=net)");
Object authnMaterials1 = /* ... */;
 
IEntity entity1 = resolver.resolve(entityUDI1, authnMaterials1);
 
// Example 2: Entity UDI in URI form (Linked Data "303" Cool URI):
 
IEntityUDI entityUDI2 = "http://www.acme.com/id/alice";
Object authnMaterials2 = /* ... */;
 
IEntity entity2 = resolver.resolve(entityUDI2, authnMaterials2);

The only difference between Example 1 and Example 2 is that a different IUDIFactory implementation is 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.

This is TBD. The current idea is that Context IDs from the Configuration API will be considered one flavor of Context UDIs, i.e. you will be able to parse and resolve them with the UDIResolver class. However, the goal is also to not require the idas.udi project at all, if all you need is read/write Context IDs in your configuration file. This will just work the same way as it does today.

Implications on existing components and concepts

Context Types

The concept of Context Types is not changed by the introduction of UDIs. Context Types are still used to look up Context Factories from the IdASRegistry.

IdASRegistry

Some functionality that is currently in IdASRegistry will be moved to the new idas.udi project, e.g.:

  • XRIs and URIs as Context IDs will becomes types of Context UDIs and moved out of IdASRegistry. This may remove idas.registry's dependency on configuration.xrds and the OpenXRI jars.
  • Eventually, it may make sense to remove the IContextId interface and ContextIdFactory class from idas.registry.

IContextFactory

It may also make sense to make the following change to IContextFactory, but this could be avoided if it causes problems to CP authors.

Current:

public interface IContextFactory extends IConfigurableComponent
 
	public IContext createContext(IContextId contextID) throws IdASException;
}

New:

public interface IContextFactory extends IConfigurableComponent
 
	public IContext createContext(Map contextConfiguration) throws IdASException;
}

Back to the top