1 /** 2 * Jin - a chess client for internet chess servers. 3 * More information is available at http://www.jinchess.com/. 4 * Copyright (C) 2002 Alexander Maryanovsky. 5 * All rights reserved. 6 * 7 * This program is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU General Public License 9 * as published by the Free Software Foundation; either version 2 10 * of the License, or (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 20 */ 21 22 package free.jin; 23 24 import java.io.IOException; 25 import free.jin.event.*; 26 import free.chess.Move; 27 import free.chess.WildVariant; 28 29 30 /** 31 * Defines the interface between the chess server and the client. 32 * Some restrictions/rules on the implementation that can't be enforced by the compiler: 33 * <UL> 34 * <LI> The implementation is responsible for firing events to registered listeners 35 * when needed. However, if a certain feature which is implied by 36 * calling the listener is not supported by the server, the implementation 37 * may ignore addListener and removeListener calls related to that feature 38 * or not fire events of that type. 39 * <LI> The calls to all the listeners must be done in the AWT event dispatching 40 * thread. 41 * <LI> The implementation is supposed to be completely self sufficient, meaning 42 * that only the methods specified in the interface are required to normally 43 * interact with it. For example, you can't require to call a special method 44 * to enable a certain feature - the implementation must decide by itself 45 * when to enable and when to disable the feature. 46 * <LI> The implementation must supress the textual message accompanying some event 47 * (sent by the server) when at least a single listener of that event is 48 * registered. On the other hand, the same textual message must NOT be 49 * supressed when there are no listeners registered. 50 * <LI> The implementation must be consistent in calling listeners. For example 51 * if a certain order of events is implied, the listeners must be called 52 * in that order - a MoveEvent must not be fired before a GameStartedEvent 53 * has been fired for that game or after a GameEndedEvent has been fired. 54 * <LI> If the server supports a certain feature only partially, the implementation 55 * is responsible for implementing the rest itself where possible 56 * and for providing default or blank values where impossible. 57 * </UL> 58 * Some assumptions the implementation is allowed to make: 59 * <UL> 60 * <LI> Although it is not guaranteed that all calls to the Connection's methods 61 * will be done in any particular thread (including the AWT Event dispatching 62 * thread), the implementation may assume that all calls from user code 63 * will be sequential, i.e. no calls to any methods will be done by the 64 * user code while one of the methods is executing from a thread other than 65 * the one executing that method. 66 * </UL> 67 * 68 * The restrictions above are to be treated as assumptions for user code and the 69 * assumptions above are to be treated as restrictions for user code.<P> 70 * 71 * If the server supports additional features beyond the specified in the 72 * interface, it may add methods supporting these features. The server specific 73 * user code, may then cast the implementation to its actual type and use 74 * these methods. If certain features are supported in an extended form (more 75 * information is sent by the server than is needed to support the interface), 76 * the implementation may (but doesn't have to) fire subclasses of the appropriate 77 * events (or return subclasses of objects in case of queries), adding the 78 * information sent by the server. The server specific user code handling the 79 * event (or issuing the query), in turn, may (but again, does not have to) 80 * cast the event (or returned object) to its actual type and retrieve the 81 * extra information. 82 */ 83 84 public interface Connection{ 85 86 87 88 /** 89 * The code for a game white won. 90 */ 91 92 int WHITE_WON = 0; 93 94 95 96 /** 97 * The code for a game white lost. 98 */ 99 100 int WHITE_LOST = 1; 101 102 103 104 /** 105 * The code for a drawn game. 106 */ 107 108 int DRAWN = 2; 109 110 111 112 /** 113 * The code for an adjourned game. 114 */ 115 116 int ADJOURNED = 3; 117 118 119 120 /** 121 * The code for an aborted game. 122 */ 123 124 int ABORTED = 4; 125 126 127 128 /** 129 * Returns the <code>ListenerManager</code> for this <code>Connection</code>. 130 * Via this object, you can register and unregister listeners for various 131 * events. 132 */ 133 getListenerManager()134 ListenerManager getListenerManager(); 135 136 137 138 /** 139 * Initiates a connect-and-login procedure. The actual procedure should be 140 * performed asynchronously, and this method should return without blocking. 141 */ 142 initiateConnectAndLogin(String hostname, int port)143 void initiateConnectAndLogin(String hostname, int port); 144 145 146 147 /** 148 * Returns true if this Connection is currently connected to the server, 149 * returns false otherwise. 150 */ 151 isConnected()152 boolean isConnected(); 153 154 155 156 /** 157 * Closes the connection. The actual disconnection should be performed 158 * asynchronously, and this method should return without blocking. 159 * This method may be invoked at any time, even if the connection is 160 * not currently connected or logged in. 161 */ 162 close()163 void close() throws IOException; 164 165 166 167 /** 168 * Returns the username of the account. This method should only be called after 169 * connect() returns. 170 */ 171 getUsername()172 String getUsername(); 173 174 175 176 /** 177 * Sends an arbitrary string to the server. Use this only for server specific 178 * commands or commands issued manually by the user. Using this method for 179 * sending other commands makes your client incompatible with other servers 180 * besides the one you are using. 181 */ 182 sendCommand(String command)183 void sendCommand(String command); 184 185 186 187 /** 188 * Sends the command closing the session to the server - this is usually "quit", 189 * or "exit". This method will not be called unless the connection is connected. 190 */ 191 exit()192 void exit(); 193 194 195 196 /** 197 * Returns a list of support wild variants. 198 */ 199 getSupportedVariants()200 WildVariant [] getSupportedVariants(); 201 202 203 204 /** 205 * Quits the given game. Whatever relation I had to this game is closed, this 206 * may mean, unobserving, resigning, unexamining or any other operation 207 * that closes the game. The passed Game object must be the one created by 208 * the implementation of this class, and not just one you created yourself. 209 */ 210 quitGame(Game game)211 void quitGame(Game game); 212 213 214 215 /** 216 * Makes the given move in the given Game. The specified <code>Game</code> 217 * must be an instance created by this <code>Connection</code>. 218 */ 219 makeMove(Game game, Move move)220 void makeMove(Game game, Move move); 221 222 223 224 /** 225 * Resigns the given game. The given game must be a played game and of type 226 * Game.MY_GAME. 227 */ 228 resign(Game game)229 void resign(Game game); 230 231 232 233 /** 234 * Sends a request to draw the given game, or if the opponent already offered 235 * a draw, accepts it. The given game must be a played game and of type 236 * <code>Game.MY_GAME</code>. 237 */ 238 requestDraw(Game game)239 void requestDraw(Game game); 240 241 242 243 /** 244 * Returns whether the server supports aborting a game. 245 */ 246 isAbortSupported()247 boolean isAbortSupported(); 248 249 250 251 /** 252 * Sends a request to abort the given game, or if the opponent already offered 253 * to abort, accepts it. The given game must be a played game and of type 254 * <code>Game.MY_GAME</code>. This method should throw an 255 * <code>UnsupportedOperationException</code> if 256 * <code>isAbortSupported</code> returns <code>false</code>. 257 */ 258 requestAbort(Game game)259 void requestAbort(Game game); 260 261 262 263 /** 264 * Returns whether the server supports adjourning a game. 265 */ 266 isAdjournSupported()267 boolean isAdjournSupported(); 268 269 270 271 /** 272 * Sends a request to adjourn the given game, or if the opponent already 273 * offered adjournment, accepts it. The given game must be a played game and 274 * of type <code>Game.MY_GAME</code>. This method should throw an 275 * <code>UnsupportedOperationException</code> if 276 * <code>isAdjournSupported</code> returns <code>false</code>. 277 */ 278 requestAdjourn(Game game)279 void requestAdjourn(Game game); 280 281 282 283 /** 284 * Returns whether the server supports one ply takebacks. 285 */ 286 isTakebackSupported()287 boolean isTakebackSupported(); 288 289 290 291 /** 292 * Sends a one ply takeback request in the given game, or if the opponent 293 * already offered a one ply takeback, accepts it. The given game must be a 294 * played game and of type <code>Game.MY_GAME</code>. This method should throw 295 * an <code>UnsupportedOperationException</code> if 296 * <code>isTakebackSupported</code> returns <code>false</code>. 297 */ 298 requestTakeback(Game game)299 void requestTakeback(Game game); 300 301 302 303 /** 304 * Returns whether the server supports multiple ply takebacks. 305 */ 306 isMultipleTakebackSupported()307 boolean isMultipleTakebackSupported(); 308 309 310 311 /** 312 * Sends a takeback request for the specified amount of plies in the given 313 * game, or if the opponent already offered a one ply takeback, accepts it. 314 * The given game must be a played game and of type <code>Game.MY_GAME</code>. 315 * This method should throw an <code>UnsupportedOperationException</code> if 316 * <code>isTakebackSupported</code> returns <code>false</code>. 317 */ 318 requestTakeback(Game game, int plyCount)319 void requestTakeback(Game game, int plyCount); 320 321 322 323 /** 324 * Goes back the given amount of plies in the given game. If the given amount 325 * of plies is bigger than the amount of plies since the beginning of the game, 326 * goes to the beginning of the game. 327 */ 328 goBackward(Game game, int plyCount)329 void goBackward(Game game, int plyCount); 330 331 332 333 /** 334 * Goes forward the given amount of plies in the given game. If the given amount 335 * of plies is bigger than the amount of plies remaining until the end of the 336 * game, goes to the end of the game. 337 */ 338 goForward(Game game, int plyCount)339 void goForward(Game game, int plyCount); 340 341 342 343 /** 344 * Goes to the beginning of the given game. 345 */ 346 goToBeginning(Game game)347 void goToBeginning(Game game); 348 349 350 351 /** 352 * Goes to the end of the given game. 353 */ 354 goToEnd(Game game)355 void goToEnd(Game game); 356 357 358 359 /** 360 * Displays help about the server. 361 */ 362 showServerHelp()363 void showServerHelp(); 364 365 366 367 /** 368 * Sends the specified question string to the server's help channel. 369 */ 370 sendHelpQuestion(String question)371 void sendHelpQuestion(String question); 372 373 374 375 } 376