2 * Created on 13-Sep-2005
4 * TODO To change the template for this generated file go to
5 * Window - Preferences - Java - Code Style - Code Templates
7 package org.vamsas.client;
9 import org.vamsas.objects.core.VAMSAS;
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
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
36 public interface IClientDocument {
39 * Get a single object.
41 * @return object referred to by id or null if it doesn't exist.
43 object getObject(VorbaId id);
45 * Get a list of objects.
47 * @return array of objects using a vector of VorbaId ids.
49 object[] getObjects(VorbaId[] ids);
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.
55 VAMSAS[] getVamsasRoots();
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)
63 void setVamsasRoots(VAMSAS[] roots);
65 * Adds a new VAMSAS root entry
66 * TODO: decide on same InvalidVamsasObject exceptions.
67 * TODO: decide if a 'removeVamsasRoot' method is really needed.
70 void addVamsasRoot(VAMSAS newroot);
72 * Returns an object with a valid VorbaId, and provenance element.
73 * The VorbaId is so the application may refer to it in
76 * Note: An object with valid VorbaId will not be reregistered.
77 * @param unregistered unregistered vamsas object
78 * @return VorbaId registered for vamsas object
80 VorbaId registerObject(object unregistered);
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
88 VorbaId[] registerObjects(object[] unregistered);
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
96 byte[] getApplicationData();
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.
102 void setApplicationData(byte[] newData);