*/
package org.vamsas.client;
+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.
* 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 {
/**
* Returns all root objects in document. All objects inherit
* from org.vamsas.client.object and have valid VorbaIds and provenance entries.
- * @return array of root Vamsas element objects. (TODO: insert correct class here)
+ * @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
+ */
+ void setVamsasRoots(VAMSAS[] roots);
+ /**
+ * Adds a new VAMSAS root entry
+ * TODO: decide on same InvalidVamsasObject exceptions.
+ * TODO: decide if a 'removeVamsasRoot' method is really needed.
+ * @param newroot
*/
- object[] getVamsasRoots();
+ 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 VorbaId registered for vamsas object
*/
* @return array of VorbaIds for the registered objects
*/
VorbaId[] 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
- */
- byte[] getApplicationData();
/**
- * 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