X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fuk%2Fac%2Fvamsas%2Fclient%2FIClientDocument.java;fp=src%2Fuk%2Fac%2Fvamsas%2Fclient%2FIClientDocument.java;h=b2d676332f3728baa909781ba38a83ed555c8965;hb=844ccad5a3fcbedec17b2af66d460f31abc7cff1;hp=5244849d43f85f785926399a6da901e6ea03dc08;hpb=6f33f705957d674dc2ab6c994a6ea87f7a91f40f;p=vamsas.git diff --git a/src/uk/ac/vamsas/client/IClientDocument.java b/src/uk/ac/vamsas/client/IClientDocument.java index 5244849..b2d6763 100644 --- a/src/uk/ac/vamsas/client/IClientDocument.java +++ b/src/uk/ac/vamsas/client/IClientDocument.java @@ -1,99 +1,125 @@ /* - * Created on 13-Sep-2005 - * - * TODO To change the template for this generated file go to - * Window - Preferences - Java - Code Style - Code Templates + * This file is part of the Vamsas Client version 0.1. + * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite, + * Andrew Waterhouse and Dominik Lindner. + * + * Earlier versions have also been incorporated into Jalview version 2.4 + * since 2008, and TOPALi version 2 since 2007. + * + * The Vamsas Client is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * The Vamsas Client is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with the Vamsas Client. If not, see . */ package uk.ac.vamsas.client; import uk.ac.vamsas.objects.core.VAMSAS; - /** - * Defines the API for the Vamsas XML Document - * as accessed by a Vamsas SimpleClient Application. - * An instance of this interface is valid for a - * particular set of user, session and application - * handles. + * Defines the API for the Vamsas XML Document as accessed by a Vamsas + * SimpleClient Application. An instance of this interface is valid for a + * particular set of user, session and application handles. + * + * It initially represents a snapshot of the XML document at a particular time - + * queriable by reference or by retrieval of root objects. It provides methods + * to make new Vobject references, These are guaranteed to be unique amongst + * existing objects in the document, all other references created by this + * Vobject's instance and all other references constructed by any other vamsas + * agents in the session. TODO: LATER: finegrained access control for + * public/private user access Finegrained access control: Since a clientDocument + * is created for a particular UserHandle, there is scope for fine grain data + * access control based on user identity. A user may also want to make private + * notes, not available to other people using the same application in the same + * session. TODO: LATER: implement a more sophisticated query interface for + * quickly identifying new data in a vamsas document and manipulating existing + * objects * - * It initially represents a snapshot of the - * XML document at a particular time - queriable by - * reference or by retrieval of root objects. - * It provides methods to make new Vobject references, - * These are guaranteed to be unique amongst existing - * objects in the document, all other references created - * by this Vobject's instance and all other references - * constructed by any other vamsas agents in the session. - * TODO: LATER: finegrained access control for public/private user access - * Finegrained access control: Since a clientDocument is created for a particular - * UserHandle, there is scope for fine grain data access - * control based on user identity. - * A user may also want to make private notes, not - * available to other people using the same application - * in the same session. - * TODO: LATER: implement a more sophisticated query interface for quickly identifying new data in a vamsas document and manipulating existing objects * @author jimp */ public interface IClientDocument { - + /** * Get a single Vobject. + * * @param id * @return Vobject referred to by id or null if it doesn't exist. */ Vobject getObject(VorbaId id); + /** * Get a list of objects. + * * @param ids * @return array of objects using a vector of VorbaId ids. */ Vobject[] getObjects(VorbaId[] ids); + /** - * Returns all root objects in document. All objects inherit - * from uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries. + * Returns all root objects in document. All objects inherit from + * uk.ac.vamsas.client.Vobject and have valid VorbaIds and provenance entries. + * * @return array of root Vamsas element objects. */ VAMSAS[] getVamsasRoots(); + /** - * set the VAMSAS roots in the document - * TODO: decide if objects are verified for provenance and VorbaIds by this call or when document is stored - * TODO: decide if this call should throw InvalidVamsasObject exceptions. - * TODO: decide how this call deals with applications that 'forget' to include all VAMSAS roots (this is where reference counting/garbage collection happens) + * set the VAMSAS roots in the document TODO: decide if objects are verified + * for provenance and VorbaIds by this call or when document is stored TODO: + * decide if this call should throw InvalidVamsasObject exceptions. TODO: + * decide how this call deals with applications that 'forget' to include all + * VAMSAS roots (this is where reference counting/garbage collection happens) + * * @param roots */ void setVamsasRoots(VAMSAS[] roots); + /** - * Adds a new VAMSAS root entry - * TODO: decide on same InvalidVamsasObject exceptions. - * TODO: decide if a 'removeVamsasRoot' method is really needed. + * Adds a new VAMSAS root entry TODO: decide on same InvalidVamsasObject + * exceptions. TODO: decide if a 'removeVamsasRoot' method is really needed. + * * @param newroot */ void addVamsasRoot(VAMSAS newroot); + /** - * Returns an Vobject with a valid VorbaId, and provenance element. - * The VorbaId is so the application may refer to it in - * its own dataspace. + * Returns an Vobject with a valid VorbaId, and provenance element. The + * VorbaId is so the application may refer to it in its own dataspace. * - * Note: An Vobject with valid VorbaId will not be reregistered. - * Advice: Calling this method for a high-level Vobject - * (such as uk.ac.vamsas.objects.core.VAMSAS) will - * register all its component objects too. + * Note: An Vobject with valid VorbaId will not be reregistered. Advice: + * Calling this method for a high-level Vobject (such as + * uk.ac.vamsas.objects.core.VAMSAS) will register all its component objects + * too. * - * @param unregistered unregistered vamsas Vobject + * @param unregistered + * unregistered vamsas Vobject * @return VorbaId registered for vamsas Vobject */ VorbaId registerObject(Vobject unregistered); + /** - * Returns an array of objects, each with a valid VorbaId - * (and completed provenance entry). - * Note: An Vobject with valid VorbaId will not be reregistered. - * @param unregistered array of unregistered objects. + * Returns an array of objects, each with a valid VorbaId (and completed + * provenance entry). Note: An Vobject with valid VorbaId will not be + * reregistered. + * + * @param unregistered + * array of unregistered objects. * @return array of VorbaIds for the registered objects */ VorbaId[] registerObjects(Vobject[] unregistered); + /** - * Get instance of Client and User specific vamsas document data access interface. + * Get instance of Client and User specific vamsas document data access + * interface. + * * @return Interface to Client and user specific application data */ IClientAppdata getClientAppdata(); -} \ No newline at end of file +}