javadoc todo
[vamsas.git] / src / uk / ac / 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 uk.ac.vamsas.client;
8
9 import uk.ac.vamsas.objects.core.VAMSAS;
10
11
12 /**
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 
17  * handles.
18  * 
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 Vobject references, 
23  * These are guaranteed to be unique amongst existing 
24  * objects in the document, all other references created 
25  * by this Vobject's instance and all other references 
26  * constructed by any other vamsas agents in the session.
27  * TODO: LATER: finegrained access control for public/private user access
28  * Finegrained access control: Since a clientDocument is created for a particular 
29  * UserHandle, there is scope for fine grain data access 
30  * control based on user identity. 
31  * A user may also want to make private notes, not 
32  * available to other people using the same application 
33  * in the same session.
34  * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects
35  * @author jimp
36  */
37 public interface IClientDocument {
38   
39   /**
40    * Get a single Vobject.
41    * @param id
42    * @return Vobject referred to by id or null if it doesn't exist.
43    */
44   Vobject getObject(VorbaId id);
45   /**
46    * Get a list of objects.
47    * @param ids
48    * @return array of objects using a vector of VorbaId ids.
49    */
50   Vobject[] getObjects(VorbaId[] ids);
51   /**
52    * Returns all root objects in document. All objects inherit 
53    * from uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries.
54    * @return array of root Vamsas element objects.
55    */
56   VAMSAS[] getVamsasRoots();
57   /**
58    * set the VAMSAS roots in the document
59    * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored
60    * TODO: decide if this call should throw InvalidVamsasObject exceptions.
61    * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens)
62    * @param roots
63    */
64   void setVamsasRoots(VAMSAS[] roots);
65   /**
66    * Adds a new VAMSAS root entry
67    * TODO: decide on same InvalidVamsasObject exceptions.
68    * TODO: decide if a 'removeVamsasRoot' method is really needed.
69    * @param newroot
70    */
71   void addVamsasRoot(VAMSAS newroot);
72   /**
73    * Returns an Vobject with a valid VorbaId, and provenance element. 
74    * The VorbaId is so the application may refer to it in 
75    * its own dataspace.
76    * 
77    * Note: An Vobject with valid VorbaId will not be reregistered.
78    * Advice: Calling this method for a high-level Vobject 
79    * (such as uk.ac.vamsas.objects.core.VAMSAS) will 
80    * register all its component objects too.
81    * 
82    * @param unregistered unregistered vamsas Vobject
83    * @return VorbaId registered for vamsas Vobject
84    */
85   VorbaId registerObject(Vobject unregistered);
86   /**
87    * Returns an array of objects, each with a valid VorbaId
88    * (and completed provenance entry).
89    * Note: An Vobject with valid VorbaId will not be reregistered.
90    * @param unregistered array of unregistered objects.
91    * @return array of VorbaIds for the registered objects
92    */
93   VorbaId[] registerObjects(Vobject[] unregistered);
94   /**
95    * Get instance of Client and User specific vamsas document data access interface.
96    * @return Interface to Client and user specific application data
97    */
98   IClientAppdata getClientAppdata();
99 }