org.dyndns.kwitte.ogc
Class ClientConnection

java.lang.Object
  java.util.Observable
      org.dyndns.kwitte.ogc.ClientConnection

public final class ClientConnection

extends java.util.Observable

A connection that receives information about running games from an OGC server. Usage example:

 
 final ClientConnection cc = new ClientConnection("TestGame");
 java.util.Observer o = new java.util.Observer() {
     public void update(Observable o, Object arg) {
         synchronized (cc) {
              for (java.util.Enumeration e = cc.getEnumeration(); 
                   e.hasMoreElements(); ) {
                  System.out.println("*** List of games: ***");
                  System.out.println(e.nextElement());
              }
          }
     }
 };
 cc.addObserver(o);
 cc.connect();
 

In most cases you will not want to use addObserver(java.util.Observer) or getEnumeration() when you want your list of games to be displayed in a javax.swing.JList. Then you may prefer getListModel(). You can also display the games in a table. Methods are thread-safe unless documented otherwise. Each message sent to or received from the server is logged at "org.dyndns.kwitte.ogc" at java.util.logging.Level.INFO.

Constructor Summary

ClientConnection()
Creates a new ClientConnection.

ClientConnection(Game game)
Creates a new ClientConnection to x.yz.to:11111 (the public OGC server).

ClientConnection(java.lang.String game)
Creates a new ClientConnection to x.yz.to:11111 (the public OGC server).

ClientConnection(java.lang.String host, int port)
Creates a new ClientConnection.

ClientConnection(java.lang.String host, int port, Game game)
Creates a new ClientConnection.

ClientConnection(java.lang.String host, int port, java.lang.String game)
Creates a new ClientConnection.

Method Summary

void	addObserver(java.util.Observer o) Adds an observer to the set of observers for this object, provided that it is not the same as some observer already in the set.
void	connect() Connects to the OGC server.
void	disconnect() Disconnects from the OGC server.
java.util.Enumeration	getEnumeration() Returns a java.util.Enumeration which will contain an Entry for each game entry on the server.
javax.swing.ListModel	getListModel() Returns a javax.swing.ListModel which contains entries of currently running games.
javax.swing.table.TableModel	getTableModel() Returns a javax.swing.table.TableModel which contains entries of currently running games.
boolean	isConnected() Returns true if and only if the connection is established.
void	setUpdateInterval(long milliseconds) Sets the time interval for the updates.
void	setVerbose(boolean verbose) Enables or disables output of send and receive protocol to stdout.

Methods inherited from class java.util.Observable

clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ClientConnection

public ClientConnection(java.lang.String game)

Creates a new ClientConnection to x.yz.to:11111 (the public OGC server).

Parameters:

game - the name of the game for which a list of games is needed. null to list all games.

ClientConnection

public ClientConnection(Game game)

Creates a new ClientConnection to x.yz.to:11111 (the public OGC server). Since a Game object is only needed when you want to run a server this constructor should only be used when a Game object is created anyway.

Parameters:

game - the Game for which a list of games is needed. null to list all games.

ClientConnection

public ClientConnection(java.lang.String host,
                        int port,
                        java.lang.String game)

Creates a new ClientConnection.

Parameters:

host - the host or IP of the OGC server from where the information about running games shall be retrieved from.

port - the port of the OGC server from where the information about running games shall be retrieved from.

game - the name of the game for which a list of games is needed. null to list all games.

Throws:

java.lang.NullPointerException - when host == null.

ClientConnection

public ClientConnection(java.lang.String host,
                        int port,
                        Game game)

Creates a new ClientConnection. Since a Game object is only needed when you want to run a server this constructor should only be used when a Game object is created anyway.

Parameters:

host - the host or IP of the OGC server from where the information about running games shall be retrieved from.

port - the port of the OGC server from where the information about running games shall be retrieved from.

game - an instance of Game which has been instantiated with the name of the game. null to list all games.

ClientConnection

public ClientConnection()

Creates a new ClientConnection. All games on the default OGC server are being listed.

ClientConnection

public ClientConnection(java.lang.String host,
                        int port)

Creates a new ClientConnection. All games on the specified OGC server are being listed.

Parameters:

host - the host or IP of the OGC server from where the information about running games shall be retrieved from.

port - the port of the OGC server from where the information about running games shall be retrieved from.

Throws:

java.lang.NullPointerException - when host == null.

Method Detail

connect

public void connect()
             throws java.io.IOException

Connects to the OGC server. Blocks until disconnect() or until an IO error occurs. As long as the connection is established (as long as this method does not return) the list of games will be up to date.

Throws:

java.io.IOException - when an IO error occurs or when a connection is already established.

See Also:

getListModel(), addObserver(java.util.Observer)

disconnect

public void disconnect()
                throws java.io.IOException

Disconnects from the OGC server. Clears the list of games as returned in getEnumeration() and getListModel(). Notifies all Observers.

Throws:

java.io.IOException - when an IO error occurs.

setVerbose

public void setVerbose(boolean verbose)

Enables or disables output of send and receive protocol to stdout. Disabled by default.

Parameters:

verbose - true to enable output, false to disable it.

getListModel

public javax.swing.ListModel getListModel()

Returns a javax.swing.ListModel which contains entries of currently running games. Any change to the entries on the OGC server will be reflected to the returned ListModel.

Returns:

a javax.swing.ListModel that reflects all changes to the list of games.

getTableModel

public javax.swing.table.TableModel getTableModel()

Returns a javax.swing.table.TableModel which contains entries of currently running games. Any change to the entries on the OGC server will be reflected to the returned TableModel.

Returns:

a javax.swing.table.TableModel that reflects all changes to the list of games.

getEnumeration

public java.util.Enumeration getEnumeration()

Returns a java.util.Enumeration which will contain an Entry for each game entry on the server.
You must synchronize on this instance while obtaining the Enumeration and iterating over it. Otherwise the results are undefined when anything changes on the server. While the instance of ClientConnection is locked no updates will be made to the ListModel and no Observers will be notified about changes on the OGC server.
Example:

 ClientConnection cc = ...;
 ...
 synchronized (cc) {
     for (Enumeration e = cc.getEnumeration(); e.hasMoreElements(); ) {
         doSomeThingWith((Entry) e.nextElement());
     }
 }
 

Returns:

an Enumeration of the entries on the OGC server for this game.

addObserver

public void addObserver(java.util.Observer o)

Adds an observer to the set of observers for this object, provided that it is not the same as some observer already in the set. The order in which notifications will be delivered to multiple observers is not specified. See class comment for java.util.Observer. All Observers will be notified when something changes in the list of games.

Parameters:

o - an observer to be added.

Throws:

java.lang.NullPointerException - if the parameter o is null.

isConnected

public boolean isConnected()

Returns true if and only if the connection is established.

Returns:

connection status

setUpdateInterval

public void setUpdateInterval(long milliseconds)

Sets the time interval for the updates. The OGC protocol requires a client to request a list of games frequently. Otherwise the OGC server would assume that this client is no longer interested in updates on the list of running games. The default value should make sure that this never happens unless you disconnect. Anyway, you can change this value if you want. The new value will apply after the next update to the OGC server if you are already connected.

Parameters:

milliseconds - the resend interval in milliseconds.

Throws:

java.lang.IllegalArgumentException - if milliseconds < 0