src/uk/ac/vamsas/client/IClientDocument.java

   1 /*
   2  * Created on 13-Sep-2005
   3  *
   4  * TODO To change the template for this generated file go to
   5  * Window - Preferences - Java - Code Style - Code Templates
   6  */
   7 package uk.ac.vamsas.client;
   8
   9 import uk.ac.vamsas.objects.core.VAMSAS;
  10
  11
  12 /**
  13  * Defines the API for the Vamsas XML Document
  14  * as accessed by a Vamsas SimpleClient Application.
  15  * An instance of this interface is valid for a
  16  * particular set of user, session and application
  17  * handles.
  18  *
  19  * It initially represents a snapshot of the
  20  * XML document at a particular time - queriable by
  21  * reference or by retrieval of root objects.
  22  * It provides methods to make new Vobject references,
  23  * These are guaranteed to be unique amongst existing
  24  * objects in the document, all other references created
  25  * by this Vobject's instance and all other references
  26  * constructed by any other vamsas agents in the session.
  27  * TODO: LATER: finegrained access control for public/private user access
  28  * Finegrained access control: Since a clientDocument is created for a particular
  29  * UserHandle, there is scope for fine grain data access
  30  * control based on user identity.
  31  * A user may also want to make private notes, not
  32  * available to other people using the same application
  33  * in the same session.
  34  * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects
  35  * @author jimp
  36  */
  37 public interface IClientDocument {
  38
  39   /**
  40    * Get a single Vobject.
  41    * @param id
  42    * @return Vobject referred to by id or null if it doesn't exist.
  43    */
  44   Vobject getObject(VorbaId id);
  45   /**
  46    * Get a list of objects.
  47    * @param ids
  48    * @return array of objects using a vector of VorbaId ids.
  49    */
  50   Vobject[] getObjects(VorbaId[] ids);
  51   /**
  52    * Returns all root objects in document. All objects inherit
  53    * from uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries.
  54    * @return array of root Vamsas element objects.
  55    */
  56   VAMSAS[] getVamsasRoots();
  57   /**
  58    * set the VAMSAS roots in the document
  59    * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored
  60    * TODO: decide if this call should throw InvalidVamsasObject exceptions.
  61    * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)
  62    * @param roots
  63    */
  64   void setVamsasRoots(VAMSAS[] roots);
  65   /**
  66    * Adds a new VAMSAS root entry
  67    * TODO: decide on same InvalidVamsasObject exceptions.
  68    * TODO: decide if a 'removeVamsasRoot' method is really needed.
  69    * @param newroot
  70    */
  71   void addVamsasRoot(VAMSAS newroot);
  72   /**
  73    * Returns an Vobject with a valid VorbaId, and provenance element.
  74    * The VorbaId is so the application may refer to it in
  75    * its own dataspace.
  76    *
  77    * Note: An Vobject with valid VorbaId will not be reregistered.
  78    * Advice: Calling this method for a high-level Vobject
  79    * (such as uk.ac.vamsas.objects.core.VAMSAS) will
  80    * register all its component objects too.
  81    *
  82    * @param unregistered unregistered vamsas Vobject
  83    * @return VorbaId registered for vamsas Vobject
  84    */
  85   VorbaId registerObject(Vobject unregistered);
  86   /**
  87    * Returns an array of objects, each with a valid VorbaId
  88    * (and completed provenance entry).
  89    * Note: An Vobject with valid VorbaId will not be reregistered.
  90    * @param unregistered array of unregistered objects.
  91    * @return array of VorbaIds for the registered objects
  92    */
  93   VorbaId[] registerObjects(Vobject[] unregistered);
  94   /**
  95    * Get instance of Client and User specific vamsas document data access interface.
  96    * @return Interface to Client and user specific application data
  97    */
  98   IClientAppdata getClientAppdata();
  99 }