/**
 * org.vamsas.client.Iclient
 * 
 */
package org.vamsas.client;

import java.beans.EventHandler;
import java.beans.PropertyChangeListener;
import java.util.EventListener;

/**
 * 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!)
 */

public interface Iclient {
  
  /**
   * Self-documenting/describing info for the application to present 
   * to the user.
   * TODO: formalise this for describing VAMSAS system, a particular 
   * Vorba client agent, and a particular session.
   * @returns string like VamsasClient v.1.1.1 (GPL) and whatever
   */
  String getAbout();

  /**
   * TODO: Is this not be the same as the SessionUrn ?
   * @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.
     * TODO: pick a better name ?
     */
    void finalizeClient();
    /**
     * register handler for updates for the current session
     */
    void addDocumentUpdateHandler(EventListener evt);
    /**
     * get vamsas document with 
     * user and app specific data
     */
    IClientDocument getClientDocument();
    /**
     * Queue new Vorba objects for storage and propagation 
     * to other clients (via Event.DOCUMENT_UPDATE based 
     * notification of document change)
     */
    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
     */
    void storeDocument(java.io.File location);
    /**
     * Add a listener to a particular event chain.
     * See org.vamsas.client.Events for allowed values for EventChain.
     * The EventChain value is passed as the propertyName in the java.bean.PropertyChangeEvent
     * TODO: build our own vamsas Event/Listener model.
     * @param EventChain Name of event. Blank/null registers handler for all events.
     * @param evt - event handler function.
     */
    void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
}