src/uk/ac/vamsas/client/IClientDocument.java

   1 /*
   2  * This file is part of the Vamsas Client version 0.1.
   3  * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite,
   4  *  Andrew Waterhouse and Dominik Lindner.
   5  *
   6  * Earlier versions have also been incorporated into Jalview version 2.4
   7  * since 2008, and TOPALi version 2 since 2007.
   8  *
   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.
  13  *
  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.
  18  *
  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/>.
  21  */
  22 package uk.ac.vamsas.client;
  23
  24 import uk.ac.vamsas.objects.core.VAMSAS;
  25
  26 /**
  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.
  30  *
  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
  43  * objects
  44  *
  45  * @author jimp
  46  */
  47 public interface IClientDocument {
  48
  49   /**
  50    * Get a single Vobject.
  51    *
  52    * @param id
  53    * @return Vobject referred to by id or null if it doesn't exist.
  54    */
  55   Vobject getObject(VorbaId id);
  56
  57   /**
  58    * Get a list of objects.
  59    *
  60    * @param ids
  61    * @return array of objects using a vector of VorbaId ids.
  62    */
  63   Vobject[] getObjects(VorbaId[] ids);
  64
  65   /**
  66    * Returns all root objects in document. All objects inherit from
  67    * uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries.
  68    *
  69    * @return array of root Vamsas element objects.
  70    */
  71   VAMSAS[] getVamsasRoots();
  72
  73   /**
  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)
  79    *
  80    * @param roots
  81    */
  82   void setVamsasRoots(VAMSAS[] roots);
  83
  84   /**
  85    * Adds a new VAMSAS root entry TODO: decide on same InvalidVamsasObject
  86    * exceptions. TODO: decide if a 'removeVamsasRoot' method is really needed.
  87    *
  88    * @param newroot
  89    */
  90   void addVamsasRoot(VAMSAS newroot);
  91
  92   /**
  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.
  95    *
  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
  99    * too.
 100    *
 101    * @param unregistered
 102    *          unregistered vamsas Vobject
 103    * @return VorbaId registered for vamsas Vobject
 104    */
 105   VorbaId registerObject(Vobject unregistered);
 106
 107   /**
 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
 110    * reregistered.
 111    *
 112    * @param unregistered
 113    *          array of unregistered objects.
 114    * @return array of VorbaIds for the registered objects
 115    */
 116   VorbaId[] registerObjects(Vobject[] unregistered);
 117
 118   /**
 119    * Get instance of Client and User specific vamsas document data access
 120    * interface.
 121    *
 122    * @return Interface to Client and user specific application data
 123    */
 124   IClientAppdata getClientAppdata();
 125 }