src/org/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 org.vamsas.client;
   8
   9 import org.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: NOW! make AppData interface instance for getting/setting 'global' appData and the current users' appData entry.
  28  * TODO: LATER: finegrained access control for public/private user access
  29  * Finegrained access control: Since a clientDocument is created for a particular
  30  * UserHandle, there is scope for fine grain data access
  31  * control based on user identity.
  32  * A user may also want to make private notes, not
  33  * available to other people using the same application
  34  * in the same session.
  35  * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects
  36  * @author jimp
  37  */
  38 public interface IClientDocument {
  39
  40   /**
  41    * Get a single Vobject.
  42    * @param id
  43    * @return Vobject referred to by id or null if it doesn't exist.
  44    */
  45   Vobject getObject(VorbaId id);
  46   /**
  47    * Get a list of objects.
  48    * @param ids
  49    * @return array of objects using a vector of VorbaId ids.
  50    */
  51   Vobject[] getObjects(VorbaId[] ids);
  52   /**
  53    * Returns all root objects in document. All objects inherit
  54    * from org.vamsas.client.Vobject and have valid VorbaIds and provenance entries.
  55    * @return array of root Vamsas element objects.
  56    */
  57   VAMSAS[] getVamsasRoots();
  58   /**
  59    * set the VAMSAS roots in the document
  60    * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored
  61    * TODO: decide if this call should throw InvalidVamsasObject exceptions.
  62    * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)
  63    * @param roots
  64    */
  65   void setVamsasRoots(VAMSAS[] roots);
  66   /**
  67    * Adds a new VAMSAS root entry
  68    * TODO: decide on same InvalidVamsasObject exceptions.
  69    * TODO: decide if a 'removeVamsasRoot' method is really needed.
  70    * @param newroot
  71    */
  72   void addVamsasRoot(VAMSAS newroot);
  73   /**
  74    * Returns an Vobject with a valid VorbaId, and provenance element.
  75    * The VorbaId is so the application may refer to it in
  76    * its own dataspace.
  77    *
  78    * Note: An Vobject with valid VorbaId will not be reregistered.
  79    * Advice: Calling this method for a high-level Vobject
  80    * (such as org.vamsas.objects.core.VAMSAS) will
  81    * register all its component objects too.
  82    *
  83    * @param unregistered unregistered vamsas Vobject
  84    * @return VorbaId registered for vamsas Vobject
  85    */
  86   VorbaId registerObject(Vobject unregistered);
  87   /**
  88    * Returns an array of objects, each with a valid VorbaId
  89    * (and completed provenance entry).
  90    * Note: An Vobject with valid VorbaId will not be reregistered.
  91    * @param unregistered array of unregistered objects.
  92    * @return array of VorbaIds for the registered objects
  93    */
  94   VorbaId[] registerObjects(Vobject[] unregistered);
  95   /**
  96    * Get instance of Client and User specific vamsas document data access interface.
  97    * @return Interface to Client and user specific application data
  98    */
  99   IClientAppdata getClientAppdata();
 100 }