/*
 * 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 java.io.File;

/**
 * Defines methods for instantiating Vorba client application agents
 * @author jimp
 *
 * (it's VORBA, not CORBA!)
 */

public interface IClientFactory {

     /**
      * Create a new Vorba Session
      * @param applicationHandle is the application's VAMSAS handle string
     * @throws NoDefaultSessionException if more than one session exists that the client may connect to
      */
     	IClient getIClient(ClientHandle applicationHandle) throws NoDefaultSessionException;
     	/**
     	 * returns new Vorba for a given session.
     	 * @param applicationHandle
     	 * @param sessionUrn session to connect to (or null to create a new session)
     	 * @return
     	 */
       IClient getIClient(ClientHandle applicationHandle, String sessionUrn);
       /**
        * returns new vorba for a  given session acting as a particular identity
        * @param applicationHandle
        * @param userId
        * @param sessionUrn session to connect to (or null to create a new session)
        * @return
        */
       IClient getIClient(ClientHandle applicationHandle, UserHandle userId, String sessionUrn);
       /**
        * New session for application and specific user
        * @param applicationHandle
        * @param userId
        * @return
       * @throws NoDefaultSessionException if more than one session exists that the client may connect to
        */
       IClient getIClient(ClientHandle applicationHandle, UserHandle userId) throws NoDefaultSessionException;
       /**
        * Create a new sesssion for the application with the current user
        * @param applicationHandle
        * @return
        */
       IClient getNewSessionIClient(ClientHandle applicationHandle);
       /**
        * Create a new session for the application using a particular user identity
        * @param applicationHandle
        * @param userId
        * @return
        */
       IClient getNewSessionIClient(ClientHandle applicationHandle, UserHandle userId);
       /**
        * Create a new session and import an existing vamsas document into it.
        * @param applicationHandle 
        * @param vamsasDocument
        * @return
        */
       IClient openAsNewSessionIClient(ClientHandle applicationHandle, File vamsasDocument) throws InvalidSessionDocumentException;
       /**
        * Create a new session as a particular user and import an existing vamsas document into it.
        * @param applicationHandle 
        * @param userId
        * @param vamsasDocument
        * @return
        */
      IClient openAsNewSessionIClient(ClientHandle applicationHandle, UserHandle userId, File vamsasDocument) throws InvalidSessionDocumentException;
       /**
        * enumerate the active sessions this IClientFactory instance knows about.
        * Can be used by caller to pick a session on catching a NoDefaultSessionException.
        * LATER: Define interface for discovering more information about a session (so it can be presented to a user in a meaningful way)
        * @return possibly empty array of sessionUrn strings
        */
       public String[] getCurrentSessions();

}