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: NOW! make AppData interface instance for getting/setting 'global' appData and the current users' appData entry.
28 * TODO: LATER: finegrained access control for public/private user access
29 * Finegrained access control: Since a clientDocument is created for a particular
30 * UserHandle, there is scope for fine grain data access
31 * control based on user identity.
32 * A user may also want to make private notes, not
33 * available to other people using the same application
34 * in the same session.
35 * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects
38 public interface IClientDocument {
41 * Get a single object.
43 * @return object referred to by id or null if it doesn't exist.
45 object getObject(VorbaId id);
47 * Get a list of objects.
49 * @return array of objects using a vector of VorbaId ids.
51 object[] getObjects(VorbaId[] ids);
53 * Returns all root objects in document. All objects inherit
54 * from org.vamsas.client.object and have valid VorbaIds and provenance entries.
55 * @return array of root Vamsas element objects.
57 VAMSAS[] getVamsasRoots();
59 * set the VAMSAS roots in the document
60 * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored
61 * TODO: decide if this call should throw InvalidVamsasObject exceptions.
62 * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)
65 void setVamsasRoots(VAMSAS[] roots);
67 * Adds a new VAMSAS root entry
68 * TODO: decide on same InvalidVamsasObject exceptions.
69 * TODO: decide if a 'removeVamsasRoot' method is really needed.
72 void addVamsasRoot(VAMSAS newroot);
74 * Returns an object with a valid VorbaId, and provenance element.
75 * The VorbaId is so the application may refer to it in
78 * Note: An object with valid VorbaId will not be reregistered.
79 * Advice: Calling this method for a high-level object
80 * (such as org.vamsas.objects.core.VAMSAS) will
81 * register all its component objects too.
83 * @param unregistered unregistered vamsas object
84 * @return VorbaId registered for vamsas object
86 VorbaId registerObject(object unregistered);
88 * Returns an array of objects, each with a valid VorbaId
89 * (and completed provenance entry).
90 * Note: An object with valid VorbaId will not be reregistered.
91 * @param unregistered array of unregistered objects.
92 * @return array of VorbaIds for the registered objects
94 VorbaId[] registerObjects(object[] unregistered);
97 * Gets the application data associated with this session's
98 * vamsas document that is accessible by the client
99 * application (and user)
100 * @return applicationData field
102 byte[] getApplicationData();
104 * Sets the application data entry associated with
105 * the application and user participating in this vamsas session.
106 * @param newData new contents of applicationData field.
108 void setApplicationData(byte[] newData);