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 object references,
  23  * These are guaranteed to be unique amongst existing
  24  * objects in the document, all other references created
  25  * by this object's instance and all other references
  26  * constructed by any other vamsas agents in the session.
  27  * TODO: Since a clientDocument is created for a particular
  28  * UserHandle, there is scope for fine grain data access
  29  * control based on user identity.
  30  * A user may also want to make private notes, not
  31  * available to other people using the same application
  32  * in the same session.
  33  * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects
  34  * @author jimp
  35  */
  36 public interface IClientDocument {
  37
  38   /**
  39    * Get a single object.
  40    * @param id
  41    * @return object referred to by id or null if it doesn't exist.
  42    */
  43   object getObject(VorbaId id);
  44   /**
  45    * Get a list of objects.
  46    * @param ids
  47    * @return array of objects using a vector of VorbaId ids.
  48    */
  49   object[] getObjects(VorbaId[] ids);
  50   /**
  51    * Returns all root objects in document. All objects inherit
  52    * from org.vamsas.client.object and have valid VorbaIds and provenance entries.
  53    * @return array of root Vamsas element objects.
  54    */
  55   VAMSAS[] getVamsasRoots();
  56   /**
  57    * set the VAMSAS roots in the document
  58    * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored
  59    * TODO: decide if this call should throw InvalidVamsasObject exceptions.
  60    * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)
  61    * @param roots
  62    */
  63   void setVamsasRoots(VAMSAS[] roots);
  64   /**
  65    * Adds a new VAMSAS root entry
  66    * TODO: decide on same InvalidVamsasObject exceptions.
  67    * TODO: decide if a 'removeVamsasRoot' method is really needed.
  68    * @param newroot
  69    */
  70   void addVamsasRoot(VAMSAS newroot);
  71   /**
  72    * Returns an object with a valid VorbaId, and provenance element.
  73    * The VorbaId is so the application may refer to it in
  74    * its own dataspace.
  75    *
  76    * Note: An object with valid VorbaId will not be reregistered.
  77    * @param unregistered unregistered vamsas object
  78    * @return VorbaId registered for vamsas object
  79    */
  80   VorbaId registerObject(object unregistered);
  81   /**
  82    * Returns an array of objects, each with a valid VorbaId
  83    * (and completed provenance entry).
  84    * Note: An object with valid VorbaId will not be reregistered.
  85    * @param unregistered array of unregistered objects.
  86    * @return array of VorbaIds for the registered objects
  87    */
  88   VorbaId[] registerObjects(object[] unregistered);
  89
  90   /**
  91    * Gets the application data associated with this session's
  92    * vamsas document that is accessible by the client
  93    * application (and user)
  94    * @return applicationData field
  95    */
  96   byte[] getApplicationData();
  97   /**
  98    * Sets the application data entry associated with
  99    * the application and user participating in this vamsas session.
 100    * @param newData new contents of applicationData field.
 101    */
 102   void setApplicationData(byte[] newData);
 103 }