/**
 * uk.ac.vamsas.client.IClient
 * 
 */
package uk.ac.vamsas.client;

import java.beans.PropertyChangeListener;
import java.io.IOException;

/**
 * Defines the methods availabable to a vamsas
 * application for interacting with its Vorba agent
 * created by an IClientFactory instance for a particular session, 
 * user, and application handle.
 * (it's VORBA, not CORBA!)
 * LATER: add exceptions for timeouts raised when there are problems accessing session data (because another application is hogging it).
 * LATER: think about situations when two applications both want a ClientDocument at the same time - can one have read-only access (and be told that another is about to update)
 */

public interface IClient {
  
  /**
   * Self-documenting/describing info for the application to present 
   * to the user.
   * LATER: formalise this for describing VAMSAS system, a particular 
   * Vorba client agent, and a particular session.
   * @return string like VamsasClient v.1.1.1 (GPL) and whatever
   */
  public String getAbout();
  
  /**
   * convenience method to get the SessionUrn as a string (for passing directly to a text box...).
   * @return current SessionUrn
   */
    public String getSessionUrn();
    /**
     * Returns a valid URN for other applications to connect to 
     * the vamsas session.
     * @return session handle for this session.
     */
    public SessionHandle getSessionHandle();
    /**
     * Included for applications with several ClientHandle 
     * identities.
     * @return ClientHandle used to interact with 
     * other Vamsas applications.
     */
    public ClientHandle getClientHandle();
    /**
     * 
     * @return UserHandle used when interacting
     * with other Vamsas applications.
     */
    public UserHandle getUserHandle();
    /**
     * Method called by client application on exit. 
     * Vorba will inform other clients if they exist. 
     * If this is the last application in the session 
     * then the session will be closed.
     * Note: The application should be ready to handle 
     * 'RequestToCloseDocument' events from the Vorba 
     * agent in the latter case and so prompt the user 
     * to save the session locally.
     * LATER: pick a better name ?
     */
    public void finalizeClient();
    /**
     * register handler for updates for the current session
     */
    public void addDocumentUpdateHandler(PropertyChangeListener evt);
    /**
     * get vamsas document with 
     * user and app specific data
     * IClientDocuments are not thread-safe.
     * TODO: New exception for failed document lock.
     * @throws IOException if lock is not obtainable for the document in the session
     */
    public IClientDocument getClientDocument() throws IOException;
    /**
     * Queue new Vorba objects for storage and propagation 
     * to other clients (via Event.DOCUMENT_UPDATE based 
     * notification of document change)
     * New objects without provenance information will be 
     * given a default entry using the IClient's application, 
     * user (and session) handles
     * Validity of IClientDocument object instances after this call is implementation dependent
     * TODO: consider refactoring to remove the redundant IClientDocument parameter for this method
     */
    public void updateDocument(IClientDocument newdoc);
    /**
     * Any application may call storeDocument to 
     * save a local copy of the current vamsas document
     * including all application specific entries.
     * 
     * @param location to write zip file
     */
    public void storeDocument(java.io.File location);
    /**
     * Any application may call importDocument to merge a stored
     * vamsasDocument into the current session.
     * Note: use a IClientFactory's implementation to make sessions out of vamsas documnts
     * LATER: VAMSAS: The IClient implementation will handle all ID 'relocations'
     * @param location
     */
    public void importDocument(java.io.File location);
    /**
     * Add a listener to a particular event chain.
     * See uk.ac.vamsas.client.Events for allowed 
     * values for EventChain.
     * The EventChain value is passed as the 
     * propertyName in the java.bean.PropertyChangeEvent
     * LATER: extend class to form own vamsas Event/Listener model.
     * @param EventChain Name of event. Blank/null registers handler for all events.
     * @param evt - event handler function.
     */
    public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
    /**
     * Sets the update handler that will be called when any updates occur to objects of type rootObject.
     * @param rootObject
     * @param handler
     */
    public void setUpdateHandler(IObjectUpdate handler);
    public IObjectUpdate getUpdateHandler(Class rootObject);
    public void removeUpdateHandler(Class rootObject);
    public IObjectUpdate[] getUpdateHandlers();
    /**
     * client application calls this to force the 
     * Vorba client to check for updates immediately.
     *
     */
    public void pollUpdate();
    
    /**
     * Client application calls this after any pre-session initialization 
     * (registering of Handlers, etc)
     * Exceptions are raised for any failures. Any stateful calls to the session prior to
     * this will result in an implicit call to joinSession - if that results in an exception
     * then the VamsasClient should raise an Error.
     * LATER: create VAMSAS exception hierarchy (in a language agnostic manner)
     */
    public void joinSession() throws Exception;
    /**
     * get the Vamsas Pick Manager for registering pick handlers and sending messages for the current session. 
     * @return an object implementing IPickManager (which maybe the same as the IClient implementer)
     */
    public uk.ac.vamsas.client.picking.IPickManager getPickManager();
    
}