uk.ac.vamsas.client
Interface IClientDocument

All Known Implementing Classes:
ClientDocument, ClientDocument

public interface IClientDocument

Defines the API for the Vamsas XML Document as accessed by a Vamsas SimpleClient Application. An instance of this interface is valid for a particular set of user, session and application handles. It initially represents a snapshot of the XML document at a particular time - queriable by reference or by retrieval of root objects. It provides methods to make new Vobject references, These are guaranteed to be unique amongst existing objects in the document, all other references created by this Vobject's instance and all other references constructed by any other vamsas agents in the session. TODO: LATER: finegrained access control for public/private user access Finegrained access control: Since a clientDocument is created for a particular UserHandle, there is scope for fine grain data access control based on user identity. A user may also want to make private notes, not available to other people using the same application in the same session. TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects

Author:
jimp

Method Summary
 void addVamsasRoot(VAMSAS newroot)
          Adds a new VAMSAS root entry TODO: decide on same InvalidVamsasObject exceptions.
 IClientAppdata getClientAppdata()
          Get instance of Client and User specific vamsas document data access interface.
 Vobject getObject(VorbaId id)
          Get a single Vobject.
 Vobject[] getObjects(VorbaId[] ids)
          Get a list of objects.
 VAMSAS[] getVamsasRoots()
          Returns all root objects in document.
 VorbaId registerObject(Vobject unregistered)
          Returns an Vobject with a valid VorbaId, and provenance element.
 VorbaId[] registerObjects(Vobject[] unregistered)
          Returns an array of objects, each with a valid VorbaId (and completed provenance entry).
 void setVamsasRoots(VAMSAS[] roots)
          set the VAMSAS roots in the document TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored TODO: decide if this call should throw InvalidVamsasObject exceptions.
 

Method Detail

getObject

public Vobject getObject(VorbaId id)
Get a single Vobject.

Parameters:
id -
Returns:
Vobject referred to by id or null if it doesn't exist.

getObjects

public Vobject[] getObjects(VorbaId[] ids)
Get a list of objects.

Parameters:
ids -
Returns:
array of objects using a vector of VorbaId ids.

getVamsasRoots

public VAMSAS[] getVamsasRoots()
Returns all root objects in document. All objects inherit from uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries.

Returns:
array of root Vamsas element objects.

setVamsasRoots

public void setVamsasRoots(VAMSAS[] roots)
set the VAMSAS roots in the document TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored TODO: decide if this call should throw InvalidVamsasObject exceptions. TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)

Parameters:
roots -

addVamsasRoot

public void addVamsasRoot(VAMSAS newroot)
Adds a new VAMSAS root entry TODO: decide on same InvalidVamsasObject exceptions. TODO: decide if a 'removeVamsasRoot' method is really needed.

Parameters:
newroot -

registerObject

public VorbaId registerObject(Vobject unregistered)
Returns an Vobject with a valid VorbaId, and provenance element. The VorbaId is so the application may refer to it in its own dataspace. Note: An Vobject with valid VorbaId will not be reregistered. Advice: Calling this method for a high-level Vobject (such as uk.ac.vamsas.objects.core.VAMSAS) will register all its component objects too.

Parameters:
unregistered - unregistered vamsas Vobject
Returns:
VorbaId registered for vamsas Vobject

registerObjects

public VorbaId[] registerObjects(Vobject[] unregistered)
Returns an array of objects, each with a valid VorbaId (and completed provenance entry). Note: An Vobject with valid VorbaId will not be reregistered.

Parameters:
unregistered - array of unregistered objects.
Returns:
array of VorbaIds for the registered objects

getClientAppdata

public IClientAppdata getClientAppdata()
Get instance of Client and User specific vamsas document data access interface.

Returns:
Interface to Client and user specific application data