/*
 * Created on 13-Sep-2005
 *
 * TODO To change the template for this generated file go to
 * Window - Preferences - Java - Code Style - Code Templates
 */
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.
 * 
 * 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.
   * @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)
   * @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.
   * @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.
   * 
   * 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
   * @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.
   * @return array of VorbaIds for the registered objects
   */
  VorbaId[] registerObjects(Vobject[] unregistered);
  /**
   * Get instance of Client and User specific vamsas document data access interface.
   * @return Interface to Client and user specific application data
   */
  IClientAppdata getClientAppdata();
}