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.

Field Summary

static URI

defaultEntityType

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)
IEntity	buildComplexAttrValue(URI dataType) Builds a complex attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IValue).
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)
ISimpleValue	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
Iterator	getEntities(String query)
Iterator	getEntities(String query, Iterator attrSelectionList) From this context, return IEntitys that match the specified SPARQL query
Iterator	getEntities(String query, Iterator attrSelectionList, IExtension[] extensions) From this context, return IEntitys that match the specified query
IEntity	getEntity(String entityID) This is the same as passing null 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(IAuthNMaterials authentication)
String	open(IAuthNMaterials 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, addAttributeValue, getAttribute, getAttributes, getSingleValuedAttribute, removeAttribute, removeAttributeValue, removeAttributeValue

Field Detail

defaultEntityType

static final URI defaultEntityType

Method Detail

open

String open(IAuthNMaterials 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(String), getEntities(String, 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 null. One or more extensions valid for this operation.

Returns:

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

Throws:

IdASException

ContextOpenException, - AuthenticationException

ContextOpenException

See Also:

close()

open

String open(IAuthNMaterials authentication)
            throws IdASException,
                   ContextOpenException

Throws:

IdASException

ContextOpenException

See Also:

#open(Object, IExtension[])

reopen

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

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

boolean isOpen(Object identity)
               throws IdASException

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

Parameters:

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

Returns:

true if this context is open as specified, false otherwise

Throws:

IdASException

getSchema

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

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

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

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

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

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

IAuthNAttributesMaterials buildAuthNAttributesMaterials()
                                                        throws IdASException

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

Throws:

IdASException

buildAttribute

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

IFilter buildFilter()
                    throws IdASException

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

Throws:

IdASException

buildAttributeAssertion

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

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

IFilterEntityTypeAssertion buildEntityTypeAssertion()
                                                    throws IdASException

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

Throws:

IdASException

buildSimpleAttrValue

ISimpleValue buildSimpleAttrValue(URI dataType,
                                  Object value)
                                  throws IdASException,
                                         InvalidTypeException

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

Example:

IValue 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

IEntity buildComplexAttrValue(URI dataType)
                              throws IdASException,
                                     InvalidTypeException

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

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

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. If null, entity should be created with default type http://www.w3.org/1999/02/22-rdf-syntax-ns#Resource

entityID - May be null. When specified, uniquely names the Entity within this Context. When null, unique Entity ID should be assigned

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

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

IEntity getEntity(String entityID)
                  throws IdASException

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

Throws:

IdASException

See Also:

getEntity(String, Iterator)

getEntity

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 <appropriate filter for entityID=name>

Parameters:

entityID - Contextually unique ID of Entity to return.

attrSelectionList - Iterator holding the URIs of IAttribute types that the caller expects to access. A nullindicates 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).

getEntities

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

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 null or empty filter causes all IEntitys to be returned.

attrSelectionList - Iterator of URIs of IAttribute types that the caller expects to access. A null 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

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 null 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 null indicates that all attributes will be read. An empty set indicates that no attributes will be read.

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

Returns:

an Iterator of IEntitys that match the filter

Throws:

IdASException

getEntities

Iterator getEntities(String query)
                     throws IdASException

Parameters:

query - SPARQL query used to constrain the set of IEntitys returned

Returns:

an Iterator of IEntitys that match the query

Throws:

IdASException

See Also:

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

getEntities

Iterator getEntities(String query,
                     Iterator attrSelectionList)
                     throws IdASException

From this context, return IEntitys that match the specified SPARQL query

Parameters:

query - SPARQL query used to constrain the set of IEntitys returned

attrSelectionList - Iterator of URIs of IAttribute types that the caller expects to access. A null 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 query

Throws:

IdASException

getEntities

Iterator getEntities(String query,
                     Iterator attrSelectionList,
                     IExtension[] extensions)
                     throws IdASException

From this context, return IEntitys that match the specified query

Parameters:

query - SPARQL query used to constrain the set of IEntitys 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 null indicates that all attributes will be read. An empty set indicates that no attributes will be read.

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

Returns:

an Iterator of IEntitys that match the query

Throws:

IdASException

verifyEntityAttributes

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:

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

Throws:

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

NoSuchEntityException - when Entity specified by entityID is not found.

applyUpdates

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

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

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

void setComponentSetting(String key,
                         Object value)
                         throws IdASException

Throws:

IdASException

See Also:

setComponentSetting(String, Object, boolean)