src/uk/ac/vamsas/client/IClientFactory.java

   1 /*
   2  * This file is part of the Vamsas Client version 0.1.
   3  * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite,
   4  *  Andrew Waterhouse and Dominik Lindner.
   5  *
   6  * Earlier versions have also been incorporated into Jalview version 2.4
   7  * since 2008, and TOPALi version 2 since 2007.
   8  *
   9  * The Vamsas Client is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * The Vamsas Client is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with the Vamsas Client.  If not, see <http://www.gnu.org/licenses/>.
  21  */
  22 package uk.ac.vamsas.client;
  23
  24 import java.io.File;
  25
  26 /**
  27  * Defines methods for instantiating Vorba client application agents
  28  *
  29  * @author jimp
  30  *
  31  *         (it's VORBA, not CORBA!)
  32  */
  33
  34 public interface IClientFactory {
  35
  36   /**
  37    * Create a new Vorba Session
  38    *
  39    * @param applicationHandle
  40    *          is the application's VAMSAS handle string
  41    * @throws NoDefaultSessionException
  42    *           if more than one session exists that the client may connect to
  43    */
  44   IClient getIClient(ClientHandle applicationHandle)
  45       throws NoDefaultSessionException;
  46
  47   /**
  48    * returns new Vorba for a given session.
  49    *
  50    * @param applicationHandle
  51    * @param sessionUrn
  52    *          session to connect to (or null to create a new session)
  53    * @return
  54    */
  55   IClient getIClient(ClientHandle applicationHandle, String sessionUrn);
  56
  57   /**
  58    * returns new vorba for a given session acting as a particular identity
  59    *
  60    * @param applicationHandle
  61    * @param userId
  62    * @param sessionUrn
  63    *          session to connect to (or null to create a new session)
  64    * @return
  65    */
  66   IClient getIClient(ClientHandle applicationHandle, UserHandle userId,
  67       String sessionUrn);
  68
  69   /**
  70    * New session for application and specific user
  71    *
  72    * @param applicationHandle
  73    * @param userId
  74    * @return
  75    * @throws NoDefaultSessionException
  76    *           if more than one session exists that the client may connect to
  77    */
  78   IClient getIClient(ClientHandle applicationHandle, UserHandle userId)
  79       throws NoDefaultSessionException;
  80
  81   /**
  82    * Create a new sesssion for the application with the current user
  83    *
  84    * @param applicationHandle
  85    * @return
  86    */
  87   IClient getNewSessionIClient(ClientHandle applicationHandle);
  88
  89   /**
  90    * Create a new session for the application using a particular user identity
  91    *
  92    * @param applicationHandle
  93    * @param userId
  94    * @return
  95    */
  96   IClient getNewSessionIClient(ClientHandle applicationHandle, UserHandle userId);
  97
  98   /**
  99    * Create a new session and import an existing vamsas document into it.
 100    *
 101    * @param applicationHandle
 102    * @param vamsasDocument
 103    * @return
 104    */
 105   IClient openAsNewSessionIClient(ClientHandle applicationHandle,
 106       File vamsasDocument) throws InvalidSessionDocumentException;
 107
 108   /**
 109    * Create a new session as a particular user and import an existing vamsas
 110    * document into it.
 111    *
 112    * @param applicationHandle
 113    * @param userId
 114    * @param vamsasDocument
 115    * @return
 116    */
 117   IClient openAsNewSessionIClient(ClientHandle applicationHandle,
 118       UserHandle userId, File vamsasDocument)
 119       throws InvalidSessionDocumentException;
 120
 121   /**
 122    * enumerate the active sessions this IClientFactory instance knows about. Can
 123    * be used by caller to pick a session on catching a
 124    * NoDefaultSessionException. LATER: Define interface for discovering more
 125    * information about a session (so it can be presented to a user in a
 126    * meaningful way)
 127    *
 128    * @return possibly empty array of sessionUrn strings
 129    */
 130   public String[] getCurrentSessions();
 131
 132 }