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
  10 /**
  11  * Defines the API for the Vamsas XML Document
  12  * as accessed by a Vamsas Client Application.
  13  * An instance of this interface is valid for a
  14  * particular set of user, session and application
  15  * handles.
  16  *
  17  * It initially represents a snapshot of the
  18  * XML document at a particular time - queriable by
  19  * reference or by retrieval of root objects.
  20  * It provides methods to make new object references,
  21  * These are guaranteed to be unique amongst existing
  22  * objects in the document, all other references created
  23  * by this object's instance and all other references
  24  * constructed by any other vamsas agents in the session.
  25  * TODO: Since a clientDocument is created for a particular
  26  * UserHandle, there is scope for fine grain data access
  27  * control based on user identity.
  28  * A user may also want to make private notes, not
  29  * available to other people using the same application
  30  * in the same session.
  31  *
  32  * @author jimp
  33  */
  34 public interface IClientDocument {
  35
  36   /**
  37    * Get a single object.
  38    * @param id
  39    * @return object referred to by id or null if it doesn't exist.
  40    */
  41   object getObject(VorbaId id);
  42   /**
  43    * Get a list of objects.
  44    * @param ids
  45    * @return array of objects using a vector of VorbaId ids.
  46    */
  47   object[] getObjects(VorbaId[] ids);
  48   /**
  49    * Returns all root objects in document. All objects inherit
  50    * from org.vamsas.client.object and have valid VorbaIds and provenance entries.
  51    * @return array of root Vamsas element objects. (TODO: insert correct class here)
  52    */
  53   object[] getVamsasRoots();
  54   /**
  55    * Returns an object with a valid VorbaId, and provenance element.
  56    * The VorbaId is so the application may refer to it in
  57    * its own dataspace.
  58    *
  59    * Note: An object with valid VorbaId will not be reregistered.
  60    * @param unregistered unregistered vamsas object
  61    * @return VorbaId registered for vamsas object
  62    */
  63   VorbaId registerObject(object unregistered);
  64   /**
  65    * Returns an array of objects, each with a valid VorbaId
  66    * (and completed provenance entry).
  67    * Note: An object with valid VorbaId will not be reregistered.
  68    * @param unregistered array of unregistered objects.
  69    * @return array of VorbaIds for the registered objects
  70    */
  71   VorbaId[] registerObjects(object[] unregistered);
  72
  73   /**
  74    * Gets the application data associated with this session's
  75    * vamsas document that is accessible by the client
  76    * application (and user)
  77    * @return applicationData field
  78    */
  79   byte[] getApplicationData();
  80   /**
  81    * Sets the application data entry associated with
  82    * the application and user participating in this vamsas session.
  83    * @param newData new contents of applicationData field.
  84    */
  85   void setApplicationData(byte[] newData);
  86 }