old-autovect-branch/libjava/classpath/examples/gnu/classpath/examples/CORBA/swing/README.html

   1 <html>
   2   <head>
   3     <title>Five-in-a-row v 0.0</title>
   4   </head>
   5   <body LANG="en-US">
   6     <h1>
   7       <i>Five-in-a-row
   8       </i> 0.0 supplementary documentation
   9     </h1>
  10     <h3>Introduction and rules
  11     </h3>
  12     <p>
  13       <i>Five-in-a-row
  14       </i> is a two player strategy game. The players
  15       are connected via network using CORBA-based RMI/IIOP protocol and
  16       make they moves with the help of the Swing-based
  17       interface. While playing, the users can also chat.
  18     </p>
  19     <p>The system consists of the single server and any number of
  20       interconnected players. The person, willing to play, starts the
  21       client and connects the server. The server redirects call to the
  22       partner that has previously connected the same server, also willing
  23       to play.
  24     </p>
  25     <p>The game desk is a field where it is possible to set O's
  26       and X'es, one per move. The goal is to get five O's in a row while
  27       preventing your partner from getting five X's in a row. Vertical,
  28       horizontal and diagonal rows are allowed. The system detects the
  29       loss-victory situation on the desk, but currently does not serve as a
  30       playing partner, requiring at least two human players for this game.
  31     </p>
  32     <p>Both players can at any time reset the game (restarting it with
  33       the same player) or leave the game (disconnecting). The disconnected
  34       player can contact the game manager again, requesting to find another
  35       partner.
  36     </p>
  37     <p>Simple as it is, the application has some features of the typical
  38       role playing game that frequently just has more states, actions,
  39       possible moves and also provides far richer graphics environment. The
  40       game manger serves as a World-Wide-Pub where you can always find a
  41       partner to play.
  42
  43       The players can made both unsynchronized (chatting, game reset and
  44       leaving) and synchronized (moves) actions. The game state changes
  45       while playing, and the set of the available actions depends on the
  46       current state. Finally, the mouse and canvas are involved. However
  47       using RMI/IIOP machinery allowed to implement all this functionality
  48       with just 13 classes (plus 4 generated), all of them being rather
  49       simple.
  50
  51       This example refers to the standard classes only and must be buildable
  52       from your IDE as long as it has any java 1.4 compiler.
  53     </p>
  54     <p>
  55       The used IIOP protocol must ensure interoperability, allowing players
  56       to use different java virtual machines and operating systems.
  57       The processors may have the opposite byte order.
  58     </p>
  59     <h3>Configuration and run
  60     </h3>
  61     <p>The game manager server executable class is
  62       <i>gnu.classpath.examples.CORBA.swing.x5.X5Server
  63       </i>. After start,
  64       it will print to console the Internet address that must be entered to
  65       the client to reach the manager.
  66     </p>
  67     <p>The client executable class it
  68       <i>gnu.classpath.examples.CORBA.swing.x5.Demo
  69       </i>.
  70     </p>
  71     <p>The game should run with GNU Classpath
  72       0.19 and Sun Microsystems java 1.5.0_04. Due later fixed bugs it will
  73       not run with the older versions of these two implementations.
  74     </p>
  75     <p>The game manager HTTP server uses port
  76       1500. Hence all firewalls between the server and the player must be
  77       configured to allow HTTP on 1500. The ports, used by the RMI/IIOP are
  78       not persistent. GNU Classpath is configured to take ports 1501, 1502
  79       and 1503 (the firewalls must allow to use them for RMI/IIOP). The
  80       CORBA implementation other than Classpath may use different port
  81       values. Unfortunately, there is no standard method to configure the
  82       used port range in a vendor-independent way.
  83     </p>
  84     <h3>The game server
  85     </h3>
  86     <p>The game manager is first reachable via http:// protocol (for
  87       instance http://123.456.7.89:1500). The simple server at this port
  88       always serves much longer string, representing the CORBA stringified
  89       object reference (IOR). The
  90       <i>Five-in-a-row&nbsp;
  91       </i>client uses
  92       this reference to find and access the remote game server object.
  93     </p>
  94     <p>If the server player queue is empty, it simply queues this player.
  95       If the queue is not empty, the server introduces the arrived player
  96       and queued player to each other as leaves the them alone. When
  97       playing, the two clients communicate with each other directly, so the
  98       server is just a &ldquo;meeting point&rdquo; where the players can
  99       find each other. The game server is a console-only application.
 100     </p>
 101     <p>The initial server http:// address must be transferred to players
 102       by some other means of communication (web chat, E-mail, link in a web
 103       site and so on). The server writes this address to the specified
 104       file, and the client can also take the default value from the same
 105       file. This is convenient when all applications run on a single
 106       machine, but also may be used to transfer the address via shared
 107       filesystem.
 108     </p>
 109     <h3>The game client
 110     </h3>
 111     <p>The clients are Swing-based GUI applications, capable for remote
 112       communication with each other and with the game manager. They have a
 113       set of predefined states and switch between these states in
 114       accordance to the preprogrammed logic. The client states are defined
 115       in the
 116       <i>State
 117       </i> interface. They are displayed in the bottom left
 118       corner of the window and are summarized in the following table:
 119     </p>
 120     <table BORDER=1 CELLPADDING=4 CELLSPACING=0 WIDTH="100%">
 121       <thead>
 122         <tr BGCOLOR="#ccccff">
 123           <th BGCOLOR="#e6e6ff">
 124             Our state
 125           </th>
 126           <th BGCOLOR="#e6e6ff">
 127             Partner state
 128           </th>
 129           <th BGCOLOR="#e6e6ff">
 130             Possible actions
 131           </th>
 132           <th BGCOLOR="#e6e6ff">
 133             Comment
 134           </th>
 135         </tr>
 136       </thead>
 137       <tbody>
 138         <tr>
 139           <td>
 140             Disconnected
 141           </td>
 142           <td>
 143             Partner not accessible
 144           </td>
 145           <td>
 146             Connect
 147           </td>
 148           <td>
 149             Initial state.
 150           </td>
 151         </tr>
 152         <tr>
 153           <td>
 154             Queued
 155           </td>
 156           <td>
 157             Partner not accessible
 158           </td>
 159           <td>
 160             Leave
 161           </td>
 162           <td>
 163             Queued by the game manager.
 164           </td>
 165         </tr>
 166         <tr>
 167           <td>
 168             I think.
 169           </td>
 170           <td>
 171             I wait for your move
 172           </td>
 173           <td>
 174             Make move, reset game, leave, chat.
 175           </td>
 176           <td>
 177             The person who waited for another player to come starts
 178             the game first.
 179           </td>
 180         </tr>
 181         <tr>
 182           <td>
 183             I wait for your move
 184           </td>
 185           <td>
 186             I think
 187           </td>
 188           <td>
 189             Chat, reset game, leave.
 190           </td>
 191           <td>
 192             After the partner makes the move, the state changes to
 193             <i>I think
 194             </i>, unless the end of game situation is detected by
 195             the desk analyzer.
 196           </td>
 197         </tr>
 198         <tr>
 199           <td>
 200             I have lost
 201           </td>
 202           <td>
 203             I have won
 204           </td>
 205           <td>
 206             Chat, reset game, leave.
 207           </td>
 208           <td>
 209             Can be entered with the help of the desk analyzer only.
 210           </td>
 211         </tr>
 212         <tr>
 213           <td>
 214             I have won
 215           </td>
 216           <td>
 217             I have lost
 218           </td>
 219           <td>
 220             Chat, reset game, leave
 221           </td>
 222           <td>
 223             Can be entered with the help of the desk analyzer only.
 224           </td>
 225         </tr>
 226         <tr>
 227           <td>
 228             Error
 229           </td>
 230           <td>
 231             Any
 232           </td>
 233           <td>
 234             Chat, leave
 235           </td>
 236           <td>
 237             This should never happen under normal work, but the demo
 238             program may be modified by the user.
 239           </td>
 240         </tr>
 241       </tbody>
 242     </table>
 243     <br>
 244     <br>
 245     As it is seen, being in one of the states, the client expects to
 246     be the partner client in a certain defined state, and both clients
 247     change they states in a synchronized manner. Each state has its own
 248     set of the available actions and each action either preserves the
 249     current state (chat, reset) or changes it following the rules. For
 250     this simple example, the state change rules are obvious.
 251     <h3>The used RMI-IIOP architecture
 252     </h3>
 253     Both player and game manager servants are derived from the
 254     <i>org.omg.PortableServer.Servant
 255     </i> and, being servants, are simply
 256     connected to the
 257     <i>POA
 258     </i>with
 259     <i>POA.servant_to_reference
 260     </i>. The
 261     first remote object (game manager) is found using the stringified
 262     object reference. No naming service is involved.
 263 </p>
 264 Where required, the CORBA objects are narrowed into required
 265 player and game manager interfaces using method
 266 <i>PortableRemoteObject.narrow(org.omg.CORBA.Object object, Class
 267   interface_class)
 268 </i>, passing the actual interface of the object as
 269 the second parameter. After narrowing, the remote side obtains
 270 possibility to invoke remote methods, defined in the interface of
 271 this object. After the first remote object is found, other objects
 272 can be simply passed as the method parameters. For instance, the game
 273 manager introduces another player by passing its reference as a
 274 parameter to the method
 275 <i>Player.start_game.
 276 </i>
 277 <h3>Class and interface summary
 278 </h3>
 279 <table BORDER=1 CELLPADDING=3 CELLSPACING=0 WIDTH="100%">
 280   <col>
 281   <col>
 282   <tr>
 283     <th COLSPAN=2 BGCOLOR="#e6e6ff">
 284       Executables classes
 285     </th>
 286   </tr>
 287   <tr>
 288     <td>
 289       Demo
 290     </td>
 291     <td>
 292       The main executable class of the game client.
 293     </td>
 294   </tr>
 295   <tr>
 296     <td>
 297       X5Server
 298     </td>
 299     <td>
 300       The main executable class of the game manager server.
 301     </td>
 302   </tr>
 303 </table>
 304 <p></p>
 305 <table BORDER=1 CELLPADDING=3 CELLSPACING=0 WIDTH="100%">
 306   <tr BGCOLOR="#ccccff">
 307     <th COLSPAN=2 BGCOLOR="#e6e6ff">
 308       Interface Summary
 309     </th>
 310   </tr>
 311   <tr>
 312     <td>
 313       GameManager
 314     </td>
 315     <td>
 316       The game manager interface.
 317     </td>
 318   </tr>
 319   <tr>
 320     <td>
 321       Player
 322     </td>
 323     <td>
 324       Defines remote methods that are invoked by another player or by
 325       the challenge server.
 326     </td>
 327   </tr>
 328   <tr>
 329     <td>
 330       State
 331     </td>
 332     <td>
 333       Defines the states in that the player can be.
 334     </td>
 335   </tr>
 336 </table>
 337 &nbsp;
 338 <table BORDER=1 CELLPADDING=3 CELLSPACING=0 WIDTH="100%">
 339   <col>
 340   <col>
 341   <tr BGCOLOR="#ccccff">
 342     <th COLSPAN=2 BGCOLOR="#e6e6ff">
 343       Class Summary
 344     </th>
 345   </tr>
 346   <tr>
 347     <td>
 348       _GameManager_Stub
 349     </td>
 350     <td>
 351       Normally generated with rmic compiler, this class represents
 352       the GameManager Stub on the client side.
 353     </td>
 354   </tr>
 355   <tr>
 356     <td>
 357       _GameManagerImpl_Tie
 358     </td>
 359     <td>
 360       Normally generated with rmic compiler, this class represents
 361       the GameManager Tie on the client side.
 362     </td>
 363   </tr>
 364   <tr>
 365     <td>
 366       _Player_Stub
 367     </td>
 368     <td>
 369       Generate with rmic, command line rmic -iiop -poa -keep
 370       gnu.classpath.examples.CORBA.swing.x5.PlayerImpl (the compiled
 371       package must be present in the current folder).
 372     </td>
 373   </tr>
 374   <tr>
 375     <td>
 376       _PlayerImpl_Tie
 377     </td>
 378     <td>
 379       Generate with rmic, command line rmic -iiop -poa -keep
 380       gnu.classpath.examples.CORBA.swing.x5.PlayerImpl (the compiled
 381       package must be present in the current folder).
 382     </td>
 383   </tr>
 384   <tr>
 385     <td>
 386       ChatConstants
 387     </td>
 388     <td>
 389       The chat color code constants, used to indicate who is talking.
 390     </td>
 391   </tr>
 392   <tr>
 393     <td>
 394       ClientFrame
 395     </td>
 396     <td>
 397       The JFrame of the GUI client.
 398     </td>
 399   </tr>
 400   <tr>
 401     <td>
 402       GameManagerImpl
 403     </td>
 404     <td>
 405       The manager connects two players into the game.
 406     </td>
 407   </tr>
 408   <tr>
 409     <td>
 410       IorReader
 411     </td>
 412     <td>
 413       Reads the remote URL.
 414     </td>
 415   </tr>
 416   <tr>
 417     <td>
 418       OrbStarter
 419     </td>
 420     <td>
 421       Starts the ORBs, involved into this application.
 422     </td>
 423   </tr>
 424   <tr>
 425     <td>
 426       PlayerImpl
 427     </td>
 428     <td>
 429       The implementation of the PlayerCommunicator, providing the
 430       local functionality.
 431     </td>
 432   </tr>
 433   <tr>
 434     <td>
 435       PlayingDesk
 436     </td>
 437     <td>
 438       Manages actions, related to the game rules and also does all
 439       painting.
 440     </td>
 441   </tr>
 442 </table>
 443 <h3>See also
 444 </h3>
 445 <p>
 446   <a HREF="http://www.javascripter.net/games/xo/xo.htm">http://www.javascripter.net/games/xo/xo.htm
 447   </a>
 448 </p>
 449 <p>
 450   <a HREF="http://www.leepoint.net/notes-java/45examples/55games/five/five.html">http://www.leepoint.net/notes-java/45examples/55games/five/five.html
 451   </a>
 452 </p>
 453 <p>Copyright
 454 </p>
 455 <p>
 456   <font COLOR="#b3b3b3">Copyright (C) 2005 Free Software Foundation,
 457     Inc. This file is part of GNU Classpath. GNU Classpath is free
 458     software; you can redistribute it and/or modify it under the terms of
 459     the GNU General Public License as published by the Free Software
 460     Foundation; either version 2, or (at your option) any later version.
 461     GNU Classpath is distributed in the hope that it will be useful, but
 462     WITHOUT ANY WARRANTY; without even the implied warranty of
 463     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 464     General Public License for more details. You should have received a
 465     copy of the GNU General Public License along with GNU Classpath; see
 466     the file COPYING. If not, write to the Free Software Foundation,
 467     Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 468     Linking this library statically or dynamically with other modules is
 469     making a combined work based on this library. Thus, the terms and
 470     conditions of the GNU General Public License cover the whole
 471     combination. As a special exception, the copyright holders of this
 472     library give you permission to link this library with independent
 473     modules to produce an executable, regardless of the license terms of
 474     these independent modules, and to copy and distribute the resulting
 475     executable under terms of your choice, provided that you also meet,
 476     for each linked independent module, the terms and conditions of the
 477     license of that module. An independent module is a module which is
 478     not derived from or based on this library. If you modify this
 479     library, you may extend this exception to your version of the
 480     library, but you are not obligated to do so. If you do not wish to do
 481     so, delete this exception statement from your version.
 482   </font>
 483 </p>
 484 <p>
 485   <br>
 486   <br>
 487 </p>
 488 <p>
 489 First version written by <a href="http://savannah.gnu.org/users/audriusa">
 490 Audrius Me&scaron;kauskas</a>
 491 </p>
 492 </body>
 493 </html>