org.eclipse.higgins.idas.api
Interface IContext

All Superinterfaces:

IHasAttributes

public interface IContext

extends IHasAttributes

As defined at http://spwiki.editme.com/Context and http://spwiki.editme.com/ContextProvider, This interface holds a set of IEntity objects.

All Contexts follow the http://www.eclipse.org/higgins/ontologies/2008/6/higgins ontology as a base. As such, each Context may have the attributes:

http://www.eclipse.org/higgins/ontologies/2008/6/higgins#contextRelation

http://www.eclipse.org/higgins/ontologies/2008/6/higgins#contextCorrelation

Also, each Context has the attribute http://www.eclipse.org/higgins/ontologies/2008/6/higgins#contextId. getContextID() provides a shortcut to access the value of this attribute.

Method Summary

IEntity	addEntity(IEntity copyFrom) Creates a new Entity for this Context by copying the data from the passed entity Note: This operation is only applied to any backing data store after applyUpdates() is called.
IEntity	addEntity(URI entityType, String entityID) Creates a new Entity for this Context. This call is typically followed by one or more calls to IHasAttributes.addAttribute(java.net.URI) on the returned IEntity Note: This operation is only applied to any backing data store after applyUpdates()
void	applyUpdates() Applies all update operations which have been called on this Context and called on any element held by this Context (including entities, attributes, attribute meta-attributes and it's value(s), and attribute values) to a backing data store.
IAttribute	buildAttribute(URI attrID) Builds an IAttribute (unassociated with any Entity).
IFilterAttributeAssertion	buildAttributeAssertion() Builds an assertion for Entity Attributes (see IHasAttributes.getAttributes() and IHasAttributes.getAttribute(URI)) which can be passed to IFilter.setAssertion(IFilterAssertion)
IAuthNAttributesMaterials	buildAuthNAttributesMaterials() Builds an IAuthNAttributesMaterials that may be used when calling open(Object)
IComplexAttrValue	buildComplexAttrValue(URI dataType) Builds a complex attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IAttributeValue).
IFilterEntityIDAssertion	buildEntityIDAssertion() Builds an assertion for Entity IDs (see IEntity.getEntityID()) which can be passed to IFilter.setAssertion(IFilterAssertion) Note that this is simply a convenience method equivalent to creating an IFilterAttributeAssertion for the http://www.eclipse.org/higgins/ontologies/2008/6/higgins#entityId attribute
IFilterEntityTypeAssertion	buildEntityTypeAssertion() Builds an assertion for Entity Types (see IEntity.getEntityType()) which can be passed to IFilter.setAssertion(IFilterAssertion)
IFilter	buildFilter() Builds an IFilter instance that may be used when calling getEntities(IFilter)
ISimpleAttrValue	buildSimpleAttrValue(URI dataType, Object value) Builds a simple attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IAttributeValue).
void	cancelUpdates() Cancels all update operations which have been called on this Context and called on any element held by this Context (including entities, attributes, attribute meta-attributes and it's value(s), and attribute values).
void	close() Closes this Context and returns it to an un-open state.
String	exportData(String filter, String representationFormat) Exports this Context.
URI	getContextID() Returns a reference to this Context.
IContextModel	getContextModel() Returns a model of the context object as it defined in the context's schema.
Iterator	getEntities(IFilter filter)
Iterator	getEntities(IFilter filter, Iterator attrSelectionList) From this context, return IEntitys that match the specified filter
Iterator	getEntities(IFilter filter, Iterator attrSelectionList, IExtension[] extensions) From this context, return IEntitys that match the specified filter
IEntity	getEntity(String entityID) This is the same as passing as the attrSelectionList in getEntity(String, Iterator)
IEntity	getEntity(String entityID, Iterator attrSelectionList) Returns the Entity matching the specified entityID.
String	getSchema() Returns the schema governing this context.
void	importData(String filter, String representationFormat) Imports this Context.
boolean	isOpen(Object identity) Tests whether this context is open and authenticated using the specified identity
String	open(Object authentication)
String	open(Object authentication, IExtension[] extensions) Opens this Context using the provided authentication object.
void	reopen() Causes this context to re-authenticate the previously passed authentication materials passed in the open(Object) or open(Object, IExtension[]) method.
void	setComponentSetting(String key, Object value)
void	setComponentSetting(String key, Object value, boolean failUnsupported) Used to update one setting element for this context.
void	setSchema(String schema) Sets the schema governing this context.
boolean	verifyEntityAttributes(String entityID, Iterator attributes) Simple method for comparing a set of attribute assertions against a Entity.

Methods inherited from interface org.eclipse.higgins.idas.api.IHasAttributes

addAttribute, addAttribute, equals, getAttribute, getAttributes, getSingleValuedAttribute, removeAttribute, removeAttributeValue, removeAttributeValue

Method Detail

open

public String open(Object authentication,
                   IExtension[] extensions)
            throws IdASException,
                   ContextOpenException

Opens this Context using the provided authentication object.

Upon success (return with no exception), this Context is in an "open" state and is available to have other methods called (such as addEntity(URI, String), exportData(String, String), getEntity(String), getEntity(String, Iterator), getEntities(IFilter), getEntities(IFilter, Iterator), importData(String, String), verifyEntityAttributes(String, Iterator)} ). Methods requiring the context to be open throw ContextNotOpenException when in an un-open state.

An open state specifies that the specified authentication materials have been used to successfully authenticate to this Context.

If this IContext is already in an open state, this throws ContextOpenException.

The antithesis of this method is close().

Parameters:

authentication - AuthN object used to open the context. This may be an instance of IAuthNAttributesMaterials or some other object used to authenticate.

extensions - may be . One or more extensions valid for this operation.

Returns:

Entity ID of the Entity representing the identity used to open the context. May be .

Throws:

IdASException

ContextOpenException, - AuthenticationException

ContextOpenException

See Also:

close()

open

public String open(Object authentication)
            throws IdASException,
                   ContextOpenException

Throws:

IdASException

ContextOpenException

See Also:

open(Object, IExtension[])

reopen

public void reopen()
            throws IdASException,
                   AuthenticationException

Causes this context to re-authenticate the previously passed authentication materials passed in the open(Object) or open(Object, IExtension[]) method. This method is called when the context is already in an open state. If the context provider no longer has access to the previously passed authentication materials, or if those materials are unable to be used to authenticate, an AuthenticationException is thrown.

Throws:

IdASException

AuthenticationException

close

public void close()
           throws IdASException

Closes this Context and returns it to an un-open state.

Methods requiring the context to be open throw ContextNotOpenException when in an un-open state.

Throws:

IdASException

isOpen

public boolean isOpen(Object identity)
               throws IdASException

Tests whether this context is open and authenticated using the specified identity

Parameters:

identity - May be . When provided, asserts that this context was opened with the specified identity. When (@code null), no identity check is performed.

Returns:

if this context is open as specified, otherwise

Throws:

IdASException

getSchema

public String getSchema()
                 throws IdASException

Returns the schema governing this context.

TODO (Doc): Add pointers to OWL.

TODO (Doc): Add (or point to) documentation which includes sample schema.

TODO (Arch)(Impl): Add method(s) which return the schema as a stream, DOM document, or other iterable object.

Returns:

schema is returned as a String in OWL-DL format.

Throws:

IdASException

setSchema

public void setSchema(String schema)
               throws IdASException

Sets the schema governing this context.

TODO (Doc): Add pointers to OWL.

TODO (Doc): Add (or point to) documentation which includes sample schema.

TODO (Arch)(Impl): Add method(s) which take the schema as a stream, DOM document, or other iterable object.

Parameters:

schema - a String in OWL-DL format.

Throws:

IdASException

getContextModel

public IContextModel getContextModel()
                              throws IdASException

Returns a model of the context object as it defined in the context's schema. Returned model could be used to analyze context's schema and discover what types of Entities are defined.

Returns:

the model of this Context.

Throws:

IdASException

getContextID

public URI getContextID()
                 throws IdASException

Returns a reference to this Context. This is a shortcut for reading the http://www.eclipse.org/higgins/ontologies/2008/6/higgins#contextId attribute on this context. This value is used in Context Relationships and used to open this Context.

Returns:

the reference to this Context.

Throws:

IdASException

exportData

public String exportData(String filter,
                         String representationFormat)
                  throws IdASException

Exports this Context.

TODO (Arch): filter format TBD

TODO (Arch): Does this export only Entities, or the entire Context (Attributes, Schema, Entities)?

Parameters:

filter - May be . Used to select a subset of this Context to be exported.

representationFormat - Indicates the format of the string to be returned. TODO (Arch)(Doc): Specify format type. Give example

Returns:

String in the form of representationFormat containing the exported Context.

Throws:

IdASException

importData

public void importData(String filter,
                       String representationFormat)
                throws IdASException

Imports this Context.

TODO (Arch): filter format TBD

TODO (Arch): Does this import only Entities, or the entire Context (Attributes, Schema, Entities)? TODO (Arch)(Doc): Discuss collisions.

Parameters:

filter - May be . Used to select a subset of the external data set to be imported.

representationFormat - Indicates the format of the external data string being specified in external. TODO (Arch)(Doc): Specify format type. Give example

Throws:

IdASException

buildAuthNAttributesMaterials

public IAuthNAttributesMaterials buildAuthNAttributesMaterials()
                                                        throws IdASException

Builds an IAuthNAttributesMaterials that may be used when calling open(Object)

Throws:

IdASException

buildAttribute

public IAttribute buildAttribute(URI attrID)
                          throws IdASException

Builds an IAttribute (unassociated with any Entity). This is used to build up IAuthNAttributesMaterials

Parameters:

attrID -

Returns:

An IAttribute

Throws:

IdASException

buildFilter

public IFilter buildFilter()
                    throws IdASException

Builds an IFilter instance that may be used when calling getEntities(IFilter)

Throws:

IdASException

buildAttributeAssertion

public IFilterAttributeAssertion buildAttributeAssertion()
                                                  throws IdASException

Builds an assertion for Entity Attributes (see IHasAttributes.getAttributes() and IHasAttributes.getAttribute(URI)) which can be passed to IFilter.setAssertion(IFilterAssertion)

Throws:

IdASException

buildEntityIDAssertion

public IFilterEntityIDAssertion buildEntityIDAssertion()
                                                throws IdASException

Builds an assertion for Entity IDs (see IEntity.getEntityID()) which can be passed to IFilter.setAssertion(IFilterAssertion) Note that this is simply a convenience method equivalent to creating an IFilterAttributeAssertion for the http://www.eclipse.org/higgins/ontologies/2008/6/higgins#entityId attribute

Throws:

IdASException

buildEntityTypeAssertion

public IFilterEntityTypeAssertion buildEntityTypeAssertion()
                                                    throws IdASException

Builds an assertion for Entity Types (see IEntity.getEntityType()) which can be passed to IFilter.setAssertion(IFilterAssertion)

Throws:

IdASException

buildSimpleAttrValue

public ISimpleAttrValue buildSimpleAttrValue(URI dataType,
                                             Object value)
                                      throws IdASException,
                                             InvalidTypeException

Builds a simple attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IAttributeValue).

Example:

IAttributeValue value = buildSimpleValue("http://www.w3.org/2001/XMLSchema/normalizedString", new String("Some Value"));

Parameters:

dataType - The type for the simple value

value - The value for the simple type.

Returns:

the built attribute value

Throws:

IdASException

InvalidTypeException

buildComplexAttrValue

public IComplexAttrValue buildComplexAttrValue(URI dataType)
                                        throws IdASException,
                                               InvalidTypeException

Builds a complex attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IAttributeValue).

Example:

TODO: do an example of building this and then adding some attributes

Parameters:

dataType - The type for the simple value

Returns:

the built attribute value

Throws:

IdASException

InvalidTypeException

addEntity

public IEntity addEntity(URI entityType,
                         String entityID)
                  throws IdASException,
                         InvalidTypeException,
                         InvalidEntityIDException,
                         EntityExistsException

Creates a new Entity for this Context.
This call is typically followed by one or more calls to IHasAttributes.addAttribute(java.net.URI) on the returned IEntity Note: This operation is only applied to any backing data store after applyUpdates()

Parameters:

entityType - The URI specifying the type of Entity being created

entityID - May be . When specified, uniquely names the Entity within this Context. When , indicates that the caller plans to later add an attribute or attributes which will be used to construct the unique Entity ID

Returns:

The resulting IEntity. This is only applied to any backing data store after applyUpdates()

Throws:

InvalidTypeException - when the entityType is invalid

InvalidEntityIDException - when the entityID is invalid

EntityExistsException - when the entityID is known to already exist

IdASException

addEntity

public IEntity addEntity(IEntity copyFrom)
                  throws IdASException,
                         EntityExistsException

Creates a new Entity for this Context by copying the data from the passed entity
Note: This operation is only applied to any backing data store after applyUpdates() is called.

Parameters:

copyFrom - an IEntity from which data is copied to construct a new Entity

Returns:

The resulting IEntity. This is only applied to any backing data store after applyUpdates() is called.

Throws:

EntityExistsException - when copyFrom is known to already exist

IdASException

getEntity

public IEntity getEntity(String entityID)
                  throws IdASException

This is the same as passing as the attrSelectionList in getEntity(String, Iterator)

Throws:

IdASException

See Also:

getEntity(String, Iterator)

getEntity

public IEntity getEntity(String entityID,
                         Iterator attrSelectionList)
                  throws IdASException

Returns the Entity matching the specified entityID. This is effectively the same as calling getEntities(org.eclipse.higgins.idas.api.IFilter) with the filter set to

Parameters:

entityID - Contextually unique ID of Entity to return.

attrSelectionList - Iterator holding the URIs of IAttribute types that the caller expects to access. A indicates that the caller expects to read all attributes. An empty set indicates that the caller expects to read no attributes. Note that this is only an indicator of what the caller expects to read. The caller may eventually end up reading more or less. The purpose of this parameter is so that a context provider which gathers data across a network connection can optimize based on the callers intended usage.

Returns:

IEntity.

Throws:

IdASException - (typically a subclass of. See below).

NoSuchEntityException - when entity specified by entityID is not found.

getEntities

public Iterator getEntities(IFilter filter)
                     throws IdASException

Returns:

an Iterator of IEntitys that match the filter

Throws:

IdASException

See Also:

This is the same as passing {@code null} as the attrSelectionList in {@link #getEntities(IFilter, Iterator)}

getEntities

public Iterator getEntities(IFilter filter,
                            Iterator attrSelectionList)
                     throws IdASException

From this context, return IEntitys that match the specified filter

Parameters:

filter - Filter used to constrain the set of IEntitys returned. A or empty filter causes all IEntitys to be returned.

attrSelectionList - Iterator of URIs of IAttribute types that the caller expects to access. A indicates that all attributes will be read. An empty set indicates that no attributes will be read.

Returns:

an Iterator of IEntitys that match the filter

Throws:

IdASException

getEntities

public Iterator getEntities(IFilter filter,
                            Iterator attrSelectionList,
                            IExtension[] extensions)
                     throws IdASException

From this context, return IEntitys that match the specified filter

Parameters:

filter - Filter used to constrain the set of IEntitys returned. A or empty filter causes all IEntitys to be returned. This behavior may be overridden by the presence of certain extensions.

attrSelectionList - Iterator of URIs of IAttribute types that the caller expects to access. A indicates that all attributes will be read. An empty set indicates that no attributes will be read.

extensions - may be . One or more extensions valid for this operation.

Returns:

an Iterator of IEntitys that match the filter

Throws:

IdASException

verifyEntityAttributes

public boolean verifyEntityAttributes(String entityID,
                                      Iterator attributes)
                               throws IdASException

Simple method for comparing a set of attribute assertions against a Entity.

TODO (Arch): This doesn't leave a way to verify that a Entity representing a group contains a specific member in its member value. We may want to consider allowing a filter to be passed here, or at least a partial attribute.

Parameters:

entityID - Contextually unique ID of Entity being verified.

attributes - Iterator of IAttribute to be compared to the Entity specified by entityID.

Returns:

if all attribute assertions in attributes are found to be equal to those attributes in the Entity specified by entityID. otherwise.

Throws:

IdASException - (typically a subclass of. See below).

NoSuchEntityException - when Entity specified by entityID is not found.

applyUpdates

public void applyUpdates()
                  throws IdASException

Applies all update operations which have been called on this Context and called on any element held by this Context (including entities, attributes, attribute meta-attributes and it's value(s), and attribute values) to a backing data store. These updates are applied atomically when possible, but may not be applied atomically by Context Providers which do not support this. Update operations which will be applied are any of the following:
addEntity(URI, String)
addEntity(IEntity)
IEntity.remove()
IHasAttributes.addAttribute(IAttribute)
IHasAttributes.addAttribute(URI)
IHasAttributes.removeAttribute(URI)
IHasAttributes.removeAttributeValue(IAttribute)
IHasAttributes#rremoveAttributeValue(URI, Object)
IAttribute.addComplexValue(URI)
IAttribute.addSimpleValue(URI, Object)
IAttribute.addValue(IAttributeValue)
IAttribute.addValue(URI)
IAttribute.remove()
IAttributeValue.remove()
ITypedValue.setData(Object)
On a successful return, all updates which have been performed on this Context or on any contained elements are said to be fully applied to the Context. Subsequent update operations must be followed by another call to applyUpdates. On error (when an exception is thrown), the updates are said to not yet fully applied to the Context. In this case, the caller may attempt to remedy the issue which caused the call to applyUpdates by performing further update operations followed by another call to applyUpdates(). Alternately, the caller may call cancelUpdates() in order to cancel all updates which have not yet been applied.

Throws:

IdASException

cancelUpdates

public void cancelUpdates()
                   throws IdASException

Cancels all update operations which have been called on this Context and called on any element held by this Context (including entities, attributes, attribute meta-attributes and it's value(s), and attribute values). Any updates which have already been applied (by calling applyUpdates()) are not canceled.

Throws:

IdASException

See Also:

applyUpdates()

setComponentSetting

public void setComponentSetting(String key,
                                Object value,
                                boolean failUnsupported)
                         throws IdASException

Used to update one setting element for this context. Oftentimes, an instance of IContext is also an IConfigurableComponent. In this case, the new setting will typically be set (or reset) in the component's settings Map

Parameters:

key - setting name

value - setting value

failUnsupported - Default false. When true, the operation will fail with {@link NotImplementedException) if the context does not support settings of this type. When true, if the context does not support settings of this type, the setting will be ignored by the context.

Throws:

IdASException

setComponentSetting

public void setComponentSetting(String key,
                                Object value)
                         throws IdASException

Throws:

IdASException

See Also:

setComponentSetting(String, Object, boolean)