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

   1 /*
   2  * This file is part of the Vamsas Client version 0.2.
   3  * Copyright 2010 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  * @note  (it's VORBA, not CORBA!)
  32  * @history added additional sessionName argument for openAsNewSessionIClient method (v0.2)
  33  */
  34
  35 public interface IClientFactory {
  36
  37   /**
  38    * Create a new Vorba Session
  39    *
  40    * @param applicationHandle
  41    *          is the application's VAMSAS handle string
  42    * @throws NoDefaultSessionException
  43    *           if more than one session exists that the client may connect to
  44    */
  45   IClient getIClient(ClientHandle applicationHandle)
  46       throws NoDefaultSessionException;
  47
  48   /**
  49    * returns new Vorba for a given session.
  50    *
  51    * @param applicationHandle
  52    * @param sessionUrn
  53    *          session to connect to (or null to create a new session)
  54    * @return
  55    */
  56   IClient getIClient(ClientHandle applicationHandle, String sessionUrn);
  57
  58   /**
  59    * returns new vorba for a given session acting as a particular identity
  60    *
  61    * @param applicationHandle
  62    * @param userId
  63    * @param sessionUrn
  64    *          session to connect to (or null to create a new session)
  65    * @return
  66    */
  67   IClient getIClient(ClientHandle applicationHandle, UserHandle userId,
  68       String sessionUrn);
  69
  70   /**
  71    * New session for application and specific user
  72    *
  73    * @param applicationHandle
  74    * @param userId
  75    * @return
  76    * @throws NoDefaultSessionException
  77    *           if more than one session exists that the client may connect to
  78    */
  79   IClient getIClient(ClientHandle applicationHandle, UserHandle userId)
  80       throws NoDefaultSessionException;
  81
  82   /**
  83    * Create a new sesssion for the application with the current user
  84    *
  85    * @param applicationHandle
  86    * @return
  87    */
  88   IClient getNewSessionIClient(ClientHandle applicationHandle);
  89
  90   /**
  91    * Create a new session for the application using a particular user identity
  92    *
  93    * @param applicationHandle
  94    * @param userId
  95    * @return
  96    */
  97   IClient getNewSessionIClient(ClientHandle applicationHandle, UserHandle userId);
  98
  99   /**
 100    * Create a new session and import an existing vamsas document into it.
 101    * Session name will inherit from vamsasDocument path.
 102    * @param applicationHandle
 103    * @param vamsasDocument
 104    * @return
 105    */
 106   IClient openAsNewSessionIClient(ClientHandle applicationHandle,
 107       File vamsasDocument) throws InvalidSessionDocumentException;
 108
 109   /**
 110    * Create a new session and import an existing vamsas document into it.
 111    *
 112    * @param applicationHandle
 113    * @param vamsasDocument
 114    * @param sessionName - preferred session name (may be null)
 115    * @return
 116    */
 117   IClient openAsNewSessionIClient(ClientHandle applicationHandle,
 118       File vamsasDocument, String sessionName) throws InvalidSessionDocumentException;
 119
 120   /**
 121    * Create a new session as a particular user and import an existing vamsas
 122    * document into it.
 123    *
 124    * @param applicationHandle
 125    * @param userId
 126    * @param vamsasDocument
 127    * @return
 128    */
 129   IClient openAsNewSessionIClient(ClientHandle applicationHandle,
 130       UserHandle userId, File vamsasDocument)
 131       throws InvalidSessionDocumentException;
 132   /**
 133    * Create a new session as a particular user and import an existing vamsas
 134    * document into it.
 135    *
 136    * @param applicationHandle
 137    * @param userId
 138    * @param vamsasDocument
 139    * @param sessionName - preferred session name (may be null)
 140    * @return
 141    */
 142   IClient openAsNewSessionIClient(ClientHandle applicationHandle,
 143       UserHandle userId, File vamsasDocument, String sessionName)
 144   throws InvalidSessionDocumentException;
 145   /**
 146    * enumerate the active sessions this IClientFactory instance knows about. Can
 147    * be used by caller to pick a session on catching a
 148    * NoDefaultSessionException. LATER: Define interface for discovering more
 149    * information about a session (so it can be presented to a user in a
 150    * meaningful way)
 151    *
 152    * @return possibly empty array of sessionUrn strings
 153    */
 154   public String[] getCurrentSessions();
 155
 156 }