2 * This file is part of the Vamsas Client version 0.2.
3 * Copyright 2010 by Jim Procter, Iain Milne, Pierre Marguerite,
4 * Andrew Waterhouse and Dominik Lindner.
6 * Earlier versions have also been incorporated into Jalview version 2.4
7 * since 2008, and TOPALi version 2 since 2007.
9 * The Vamsas Client is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
14 * The Vamsas Client is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with the Vamsas Client. If not, see <http://www.gnu.org/licenses/>.
22 package uk.ac.vamsas.client;
24 import uk.ac.vamsas.objects.core.VAMSAS;
27 * Defines the API for the Vamsas XML Document as accessed by a Vamsas
28 * SimpleClient Application. An instance of this interface is valid for a
29 * particular set of user, session and application handles.
31 * It initially represents a snapshot of the XML document at a particular time -
32 * queriable by reference or by retrieval of root objects. It provides methods
33 * to make new Vobject references, These are guaranteed to be unique amongst
34 * existing objects in the document, all other references created by this
35 * Vobject's instance and all other references constructed by any other vamsas
36 * agents in the session. TODO: LATER: finegrained access control for
37 * public/private user access Finegrained access control: Since a clientDocument
38 * is created for a particular UserHandle, there is scope for fine grain data
39 * access control based on user identity. A user may also want to make private
40 * notes, not available to other people using the same application in the same
41 * session. TODO: LATER: implement a more sophisticated query interface for
42 * quickly identifying new data in a vamsas document and manipulating existing
47 public interface IClientDocument {
50 * Get a single Vobject.
53 * @return Vobject referred to by id or null if it doesn't exist.
55 Vobject getObject(VorbaId id);
58 * Get a list of objects.
61 * @return array of objects using a vector of VorbaId ids.
63 Vobject[] getObjects(VorbaId[] ids);
66 * Returns all root objects in document. All objects inherit from
67 * uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries.
69 * @return array of root Vamsas element objects.
71 VAMSAS[] getVamsasRoots();
74 * set the VAMSAS roots in the document TODO: decide if objects are verified
75 * for provenance and VorbaIds by this call or when document is stored TODO:
76 * decide if this call should throw InvalidVamsasObject exceptions. TODO:
77 * decide how this call deals with applications that 'forget' to include all
78 * VAMSAS roots (this is where reference counting/garbage collection happens)
82 void setVamsasRoots(VAMSAS[] roots);
85 * Adds a new VAMSAS root entry TODO: decide on same InvalidVamsasObject
86 * exceptions. TODO: decide if a 'removeVamsasRoot' method is really needed.
90 void addVamsasRoot(VAMSAS newroot);
93 * Returns an Vobject with a valid VorbaId, and provenance element. The
94 * VorbaId is so the application may refer to it in its own dataspace.
96 * Note: An Vobject with valid VorbaId will not be reregistered. Advice:
97 * Calling this method for a high-level Vobject (such as
98 * uk.ac.vamsas.objects.core.VAMSAS) will register all its component objects
101 * @param unregistered
102 * unregistered vamsas Vobject
103 * @return VorbaId registered for vamsas Vobject
105 VorbaId registerObject(Vobject unregistered);
108 * Returns an array of objects, each with a valid VorbaId (and completed
109 * provenance entry). Note: An Vobject with valid VorbaId will not be
112 * @param unregistered
113 * array of unregistered objects.
114 * @return array of VorbaIds for the registered objects
116 VorbaId[] registerObjects(Vobject[] unregistered);
119 * Get instance of Client and User specific vamsas document data access
122 * @return Interface to Client and user specific application data
124 IClientAppdata getClientAppdata();