org.eclipse.higgins.idas.api
Interface IContext

public interface IContext

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

Method Summary

IContextRelationship	addRelationship(URI relationshipType) Adds a context relationship to this context.
IDigitalSubject	addSubject(IDigitalSubject copyFrom) Creates a new Digital Subject for this Context by copying the data from the passed subject Note: This operation is only applied to any backing data store after applyUpdates() is called.
IDigitalSubject	addSubject(URI type, String subjectID) Creates a new Digital Subject for this Context. This call is typically followed by one or more calls to IHasAttributes.addAttribute(java.net.URI), IHasMetadata.addMetadata(java.net.URI) on the returned IDigitalSubject 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 digital subjects, metadata, attributes, attribute metadata and it's value(s), and attribute values) to a backing data store.
IAttribute	buildAttribute(URI attrID) Builds an IAttribute (unassociated with any digital subject).
IFilterAttributeAssertion	buildAttributeAssertion() Builds an assertion for Digital Subject 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 type) Builds a complex attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IAttributeValue).
IFilterCUIDAssertion	buildCUIDAssertion() Builds an assertion for Digital Subject CUIDs (see IDigitalSubject.getSubjectID()) which can be passed to IFilter.setAssertion(IFilterAssertion)
IFilter	buildFilter() Builds an IFilter instance that may be used when calling getSubjects(IFilter)
IFilterMetadataAssertion	buildMetadataAssertion() Builds an assertion for Digital Subject Metadata (see IHasMetadata.getMetadataSet()) which can be passed to IFilter.setAssertion(IFilterAssertion)
IContextRelationship	buildRelationship(URI type) Builds a relationship to be passed to addRelationship(URI).
ISimpleAttrValue	buildSimpleAttrValue(URI type, Object value) Builds a simple attribute value to be passed to IFilterAttributeAssertion.setAssertionValue(IAttributeValue).
IFilterTypeAssertion	buildTypeAssertion() Builds an assertion for Digital Subject Types (see IDigitalSubject.getType()) which can be passed to IFilter.setAssertion(IFilterAssertion)
void	cancelUpdates() Cancels all update operations which have been called on this Context and called on any element held by this Context (including digital subjects, metadata, attributes, attribute metadata 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.
IContextModel	getContextModel() Returns a model of the context object as it defined in the context's schema.
URI	getContextRef() Returns a reference to this Context.
IModel	getModel(URI elementType) Returns a model of whatever is named by the passed identifier
Iterator	getRelationships() Returns the relationships this Object has to others.
String	getSchema() Returns the schema governing this context.
IDigitalSubject	getSubject(String cuid) This is the same as passing null as the attrSelectionList in getSubject(String, Iterator)
IDigitalSubject	getSubject(String cuid, Iterator attrSelectionList) Returns the Digital Subject matching the specified cuid.
Iterator	getSubjects(IFilter filter)
Iterator	getSubjects(IFilter filter, Iterator attrSelectionList) From this context, return IDigitalSubjects that match the specified filter
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) Opens this Context using the provided authentication object.
void	setSchema(String schema) Sets the schema governing this context.
boolean	verifySubjectAttributes(String cuid, Iterator attributes) Simple method for comparing a set of attribute assertions against a Digital Subject.

Method Detail

open

public String open(Object authentication)
            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 addRelationship(URI), addSubject(URI, String), exportData(String, String), getRelationships(), getSubject(String), getSubject(String, Iterator), getSubjects(IFilter), getSubjects(IFilter, Iterator), importData(String, String), verifySubjectAttributes(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.

Returns:

cuid of the DigitalSubject representing the identity used to open the context. May be null.

Throws:

IdASException

ContextOpenException, - AuthenticationException

ContextOpenException

See Also:

close()

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 analyse context's schema and discover what types of Digital Subjects are defined.

Returns:

the model of this Context.

Throws:

IdASException

getModel

public IModel getModel(URI elementType)
                throws IdASException

Returns a model of whatever is named by the passed identifier

Parameters:

elementType - A URI that names a type of element (this could be an attribute ID, attribute value type, etc.)

Returns:

the model of the specified element type.

Throws:

IdASException

getContextRef

public URI getContextRef()
                  throws IdASException

Returns a reference to 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 Digital Subjects, or the entire Context (Metadata, Schema, DS, Relationships)?

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 Digital Subjects, or the entire Context (Metadata, Schema, DS, Relationships)? 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 digital subject). 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 getSubjects(IFilter)

Throws:

IdASException

buildAttributeAssertion

public IFilterAttributeAssertion buildAttributeAssertion()
                                                  throws IdASException

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

Throws:

IdASException

buildCUIDAssertion

public IFilterCUIDAssertion buildCUIDAssertion()
                                        throws IdASException

Builds an assertion for Digital Subject CUIDs (see IDigitalSubject.getSubjectID()) which can be passed to IFilter.setAssertion(IFilterAssertion)

Throws:

IdASException

buildMetadataAssertion

public IFilterMetadataAssertion buildMetadataAssertion()
                                                throws IdASException

Builds an assertion for Digital Subject Metadata (see IHasMetadata.getMetadataSet()) which can be passed to IFilter.setAssertion(IFilterAssertion)

Throws:

IdASException

buildTypeAssertion

public IFilterTypeAssertion buildTypeAssertion()
                                        throws IdASException

Builds an assertion for Digital Subject Types (see IDigitalSubject.getType()) which can be passed to IFilter.setAssertion(IFilterAssertion)

Throws:

IdASException

buildSimpleAttrValue

public ISimpleAttrValue buildSimpleAttrValue(URI type,
                                             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:

type - 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 type)
                                        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:

type - The type for the simple value

Returns:

the built attribute value

Throws:

IdASException

InvalidTypeException

buildRelationship

public IContextRelationship buildRelationship(URI type)
                                       throws IdASException

Builds a relationship to be passed to addRelationship(URI).

Parameters:

type - The type of relationship. TODO (Doc): give example.

Returns:

The resulting Relationship.

Throws:

IdASException

addSubject

public IDigitalSubject addSubject(URI type,
                                  String subjectID)
                           throws IdASException,
                                  InvalidTypeException,
                                  InvalidSubjectIDException,
                                  SubjectExistsException

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

Parameters:

type - The URI specifying the type of Digital Subject being created

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

Returns:

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

Throws:

InvalidTypeException - when the type is invalid

InvalidSubjectIDException - when the subjectID is invalid

SubjectExistsException - when the subjectID is known to already exist

IdASException

addSubject

public IDigitalSubject addSubject(IDigitalSubject copyFrom)
                           throws IdASException,
                                  SubjectExistsException

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

Parameters:

copyFrom - an IDigitalSubject from which data is copied to construct a new Digital Subject

Returns:

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

Throws:

SubjectExistsException - when Subject is known to already exist

IdASException

getSubject

public IDigitalSubject getSubject(String cuid)
                           throws IdASException

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

Throws:

IdASException

See Also:

getSubject(String, Iterator)

getSubject

public IDigitalSubject getSubject(String cuid,
                                  Iterator attrSelectionList)
                           throws IdASException

Returns the Digital Subject matching the specified cuid. This is effectively the same as calling getSubjects(org.eclipse.higgins.idas.api.IFilter) with the filter set to

TODO (Arch)(Doc): discuss whether modifications to the returned IDigitalSubject affect the stored subject.

Parameters:

cuid - Contextually Unique ID of Digital Subject to return.

attrSelectionList - Iterator holding the 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:

IDigitalSubject.

Throws:

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

NoSuchSubjectException - when subject specified by cuid is not found.

getSubjects

public Iterator getSubjects(IFilter filter)
                     throws IdASException

Returns:

an Iterator of IDigitalSubjects that match the filter

Throws:

IdASException

See Also:

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

getSubjects

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

From this context, return IDigitalSubjects that match the specified filter

Parameters:

filter - Filter used to constrain the set of IDigitalSubjects returned. A or empty filter causes all IDigitalSubjects 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 IDigitalSubjects that match the filter

Throws:

IdASException

verifySubjectAttributes

public boolean verifySubjectAttributes(String cuid,
                                       Iterator attributes)
                                throws IdASException

Simple method for comparing a set of attribute assertions against a Digital Subject.

TODO (Arch): This doesn't leave a way to verify that a DS 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:

cuid - Contextually Unique ID of Digital Subject being verified.

attributes - Iterator of IAttribute to be compared to the Digital Subject specified by cuid.

Returns:

if all attribute assertions in attributes are found to be equal to those attributes in the Digital Subject specified by cuid. otherwise.

Throws:

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

NoSuchSubjectException - when subject specified by cuid is not found.

getRelationships

public Iterator getRelationships()
                          throws IdASException

Returns the relationships this Object has to others.

Returns:

Iterator of IContextRelationship objects. The set of Relationships this Object has.

Throws:

IdASException

addRelationship

public IContextRelationship addRelationship(URI relationshipType)
                                     throws IdASException

Adds a context relationship to this context. This call is typically followed by a call to IContextRelationship.addRelatedContext(URI) Note: This operation is only applied to any backing data store after applyUpdates() is called.

Parameters:

relationshipType - The type of relationship to add.

Throws:

IdASException

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 digital subjects, metadata, attributes, attribute metadata 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:
addSubject(URI, String)
IDigitalSubject.remove()
IHasAttributes.addAttribute(URI)
IHasMetadata.addMetadata(URI)
IAttribute.remove()
IAttribute.addValue(URI)
IAttribute.addSimpleValue(URI, Object)
IAttribute.addComplexValue(URI)
IAttributeValue.remove()
ITypedValue.setData(Object)
ITypedValue.setData(Object)
On a successful return, all updates which have been performed on this Contet 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().

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 digital subjects, metadata, attributes, attribute metadata 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()