introduced org.vamsas.client.IClientAppData interface to get and set app-global and...

[vamsas.git] / src / org / vamsas / client / IClientDocument.java

diff --git a/src/org/vamsas/client/IClientDocument.java b/src/org/vamsas/client/IClientDocument.java
index df20713..84149b6 100644 (file)
--- a/src/org/vamsas/client/IClientDocument.java
+++ b/src/org/vamsas/client/IClientDocument.java
@@ -6,11 +6,12 @@
  */
 package org.vamsas.client;
 
-import java.util.Vector;
+import org.vamsas.objects.core.VAMSAS;
+
 
 /**
  * Defines the API for the Vamsas XML Document 
- * as accessed by a Vamsas Client Application.
+ * as accessed by a Vamsas SimpleClient Application.
  * An instance of this interface is valid for a 
  * particular set of user, session and application 
  * handles.
@@ -22,14 +23,16 @@ import java.util.Vector;
  * These are guaranteed to be unique amongst existing 
  * objects in the document, all other references created 
  * by this object's instance and all other references 
- * constructed by any other vamsas agents in the session.   
- * TODO: Since a clientDocument is created for a particular 
+ * constructed by any other vamsas agents in the session.
+ * TODO: NOW! make AppData interface instance for getting/setting 'global' appData and the current users' appData entry.   
+ * TODO: LATER: finegrained access control for public/private user access
+ * Finegrained access control: Since a clientDocument is created for a particular 
  * UserHandle, there is scope for fine grain data access 
  * control based on user identity. 
  * A user may also want to make private notes, not 
  * available to other people using the same application 
  * in the same session.
- * 
+ * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects
  * @author jimp
  */
 public interface IClientDocument {
@@ -48,36 +51,50 @@ public interface IClientDocument {
   object[] getObjects(VorbaId[] ids);
   /**
    * Returns all root objects in document. All objects inherit 
-   * from org.vamsas.client.object and have valid VorbaIds.
-   * @return array of root Vamsas element objects. (TODO: insert correct class here)
+   * from org.vamsas.client.object and have valid VorbaIds and provenance entries.
+   * @return array of root Vamsas element objects.
+   */
+  VAMSAS[] getVamsasRoots();
+  /**
+   * set the VAMSAS roots in the document
+   * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored
+   * TODO: decide if this call should throw InvalidVamsasObject exceptions.
+   * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)
+   * @param roots
    */
-  object[] getVamsasRoots();
+  void setVamsasRoots(VAMSAS[] roots);
   /**
-   * Returns an object with a valid VorbaId so the 
-   * application may refer to it in its own dataspace.
+   * Adds a new VAMSAS root entry
+   * TODO: decide on same InvalidVamsasObject exceptions.
+   * TODO: decide if a 'removeVamsasRoot' method is really needed.
+   * @param newroot
+   */
+  void addVamsasRoot(VAMSAS newroot);
+  /**
+   * Returns an object with a valid VorbaId, and provenance element. 
+   * The VorbaId is so the application may refer to it in 
+   * its own dataspace.
+   * 
    * Note: An object with valid VorbaId will not be reregistered.
+   * Advice: Calling this method for a high-level object 
+   * (such as org.vamsas.objects.core.VAMSAS) will 
+   * register all its component objects too.
+   * 
    * @param unregistered unregistered vamsas object
-   * @return registered vamsas object
+   * @return VorbaId registered for vamsas object
    */
-  object registerObject(object unregistered);
+  VorbaId registerObject(object unregistered);
   /**
-   * Returns an array of objects, each with a valid VorbaId.
+   * Returns an array of objects, each with a valid VorbaId
+   * (and completed provenance entry).
    * Note: An object with valid VorbaId will not be reregistered.
    * @param unregistered array of unregistered objects.
-   * @return array of registered objects
-   */
-  object[] registerObjects(object[] unregistered);
-  /**
-   * Gets the application data associated with this session's
-   * vamsas document that is accessible by the client 
-   * application (and user)
-   * @return applicationData field
+   * @return array of VorbaIds for the registered objects
    */
-  byte[] getApplicationData();
+  VorbaId[] registerObjects(object[] unregistered);
   /**
-   * Sets the application data entry associated with 
-   * the application and user participating in this vamsas session.
-   * @param newData new contents of applicationData field.
+   * Get instance of Client and User specific vamsas document data access interface.
+   * @return Interface to Client and user specific application data
    */
-  void setApplicationData(byte[] newData);
+  IClientAppdata getClientAppdata();
 }
\ No newline at end of file