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