org.eclipse.higgins.idas
Interface IContext

Package class diagram package IContext
All Superinterfaces:
IHasMetadata, IHasRelationships<URI>

public interface IContext
extends IHasMetadata, IHasRelationships<URI>

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

Note that the IHasRelationships interface takes a URI type. This URI is a Context Referenece to the related IContext. TODO: Should there be a removeDigitalSubject method which takes a filter? Similar notion could apply to other update operations as they are added.


Method Summary
 void close()
          Closes this Context and returns it to an un-open state.
 String createSubject(URI subjectType, Iterable<IAttribute> attributes)
          Creates and adds a Digital Subject to this Context.
 String exportData(String filter, String representationFormat)
          Exports this Context.
 URI getContextRef()
          Returns a reference to this Context.
 String getSchema()
          Returns the schema governing this context.
 IDigitalSubject getSubject(String cuid)
          Returns the Digital Subject matching the specified cuid.
 Iterable<IDigitalSubject> getSubjects(String filter)
          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
 void open(Object identity)
          Opens this Context using the provided identity.
 void removeSubject(String cuid)
          Removes a Digital Subject from this Context.
 void updateSubject(String cuid, Iterable<IAttribute> attributes)
          Add or change the attributes of a Digital Subject.
 boolean verifySubjectAttributes(String cuid, Iterable<IAttribute> attributes)
          Simple method for comparing a set of attribute assertions against a Digital Subject.
 
Methods inherited from interface org.eclipse.higgins.idas.IHasMetadata
addMetadata, createMetadata, getMetadataSet, removeMetadata
 
Methods inherited from interface org.eclipse.higgins.idas.IHasRelationships
addRelationship, createRelationship, getRelationships, removeRelationship
 

Method Detail

open

void open(Object identity)
          throws IdASException,
                 ContextOpenException
Opens this Context using the provided identity.

Upon success (return with no exception), this Context is in an "open" state and is available to have other methods (such as getSubject(String), getSubjects(String), createSubject(URI, Iterable), removeSubject(String), verifySubjectAttributes(String, Iterable), updateSubject(String, Iterable), exportData(String, String), importData(String, String), ) called. Methods requiring the context to be open throw ContextNotOpenException when in an un-open state.

An open state specifies that the authentication materials in the identity argument 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:
identity - AuthN identity used to open the context.
Throws:
IdASException
ContextOpenException
See Also:
close()

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: Add pointers to OWL.

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

TODO: 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

getContextRef

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

String exportData(String filter,
                  String representationFormat)
                  throws IdASException
Exports this Context.

TODO: filter format TBD

TODO: Does this export only Digital Subjects, or the entire Context (Metadata, Schema, DS, Relationships)?

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: 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: filter format TBD

TODO: Does this import only Digital Subjects, or the entire Context (Metadata, Schema, DS, Relationships)? TODO: 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: Specify format type. Give example
Throws:
IdASException

getSubject

IDigitalSubject getSubject(String cuid)
                           throws IdASException
Returns the Digital Subject matching the specified cuid. This is effectively the same as calling getSubjects(java.lang.String) with the filter set to <appropriate filter for cuid=name>

TODO: we need a way to present a properties constraint. This is to help providers which are gathering their data from expensive sources (i.e. ldap server). We don't want to cause multiple network hits, or extra data to be gathered.

TODO: discuss whether modifications to the returned IDigitalSubject affect the stored subject.

Parameters:
cuid - Contextually Unique ID of Digital Subject to return.

Returns:
IDigitalSubject.
Throws:
IdASException - (typically a subclass of. See below).
NoSuchSubjectException - when subject specified by cuid is not found.

getSubjects

Iterable<IDigitalSubject> getSubjects(String filter)
                                      throws IdASException
From this context, return IDigitalSubjects that match the specified filter

TODO: define filter format.

TODO: add param: Set attributeSelection which is "The attributes on IDigitalSubject objects which will be read by the caller. An empty set or null indicates that all attributes will be read."

Parameters:
filter - Filter used to constrain the set of IDigitalSubjects returned. A null or empty value causes all IDigitalSubjects to be returned.
Returns:
An Iterable set of IDigitalSubjects
Throws:
IdASException

createSubject

String createSubject(URI subjectType,
                     Iterable<IAttribute> attributes)
                     throws IdASException
Creates and adds a Digital Subject to this Context.

Parameters:
subjectType - The type of Digital Subject being created. TODO: add example URI to a higgins person.
attributes - The attributes of the Digital Subject being created. Attributes required by the definition of the subjectType must be included.
Returns:
The cuid of the Digital Subject which was added as a result of this operation.
Throws:
IdASException

removeSubject

void removeSubject(String cuid)
                   throws IdASException
Removes a Digital Subject from this Context.

Parameters:
cuid - Contextually Unique ID of the Digital Subject to be removed from this Context.

Throws:
IdASException - (typically a subclass of. See below).
NoSuchSubjectException - when subject specified by cuid is not found.

verifySubjectAttributes

boolean verifySubjectAttributes(String cuid,
                                Iterable<IAttribute> attributes)
                                throws IdASException
Simple method for comparing a set of attribute assertions against a Digital Subject.

TODO: This doesn't leave a way to verify that a DS representing a group contains a specific member in its member value.

Parameters:
cuid - Contextually Unique ID of Digital Subject being verified.
attributes - Set of attributes to be compared to the Digital Subject specified by cuid.
Returns:
true if all attribute assertions in attributes are found to be equal to those attributes in the Digital Subject specified by cuid. false otherwise.
Throws:
IdASException - (typically a subclass of. See below).
NoSuchSubjectException - when subject specified by cuid is not found.

updateSubject

void updateSubject(String cuid,
                   Iterable<IAttribute> attributes)
                   throws IdASException
Add or change the attributes of a Digital Subject.

TODO: This doesn't allow deletion of an attribute. TODO: This doesn't allow update operations on attribute parts (such as adding a single member of a member value) TODO: Discuss transactional semantics. Is this guaranteed to fully succeed or fully fail?

Parameters:
cuid - Contextually Unique ID of Digital Subject being updated.

attributes - Iterable set of attributes to be added or replaced.
Throws:
IdASException


Copyright © 2006 Novell Inc. All Rights Reserved.
This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html

Contributors:
  Jim Sermersheim (Novell, Inc.) - initial API and implementation