soc.util
Class SOCGameList

java.lang.Object
  soc.util.SOCGameList

Direct Known Subclasses:

SOCGameListAtServer

public class SOCGameList
extends java.lang.Object

A class for creating and tracking the games; contains each game's name, game options, SOCGame object, and mutex for synchronization.

In 1.1.07, moved from soc.server to soc.util package for client's use. Some methods moved to new subclass SOCGameListAtServer. That subclass also tracks each game's clients (StringConnections).

The client-side addGame methods allow game names to have a prefix which marks them as unjoinable by the client (SOCGames.MARKER_THIS_GAME_UNJOINABLE). If the game name has this prefix, its SOCGameList.GameInfo.canJoin flag is set to false, as queried by isUnjoinableGame(String). The prefix is stripped within addGame, and not stored as part of the game name in this list. Besides addGame, never supply this prefix to a SOCGameList method taking a game name; supply the game name without the prefix.

Author:

Robert S. Thomas

Nested Class Summary

protected static class

SOCGameList.GameInfo Holds most information on one game, except its SOCGame object, which is kept separately.

Field Summary

protected java.util.Hashtable<java.lang.String,SOCGame>	gameData synchronized map of game names to SOCGame objects
protected java.util.Hashtable<java.lang.String,SOCGameList.GameInfo>	gameInfo key = String, value = SOCGameList.GameInfo; includes mutexes to synchronize game state access, game options, and other per-game info
protected boolean	inUse used with gamelist's monitor

Constructor Summary

SOCGameList()
constructor

Method Summary

protected void	addGame(java.lang.String gaName, java.util.Map<java.lang.String,SOCGameOption> gaOpts, java.lang.String gaOptsStr, boolean cannotJoin) Internal use - Add this game name, with game options.
void	addGame(java.lang.String gaName, java.lang.String gaOptsStr, boolean cannotJoin) Client-side - Add this game name, with game options.
void	addGames(java.lang.Iterable<?> gamelist, int ourVersion) Add several games to this GameList.
void	addGames(SOCGameList gl, int ourVersion) Add the contents of another GameList to this GameList.
void	deleteGame(java.lang.String gaName) Remove the game from the list and call SOCGame.destroyGame().
SOCGame	getGameData(java.lang.String gaName) get a game's SOCGame, if we've stored that
java.util.Set<java.lang.String>	getGameNames() Get the names of every game we know about, even those with no SOCGame object.
java.util.Map<java.lang.String,SOCGameOption>	getGameOptions(java.lang.String gaName) get a game's SOCGameOptions, if stored and parsed
java.lang.String	getGameOptionsString(java.lang.String gaName) get a game's SOCGameOptions, as a packed string
java.util.Collection<SOCGame>	getGamesData() Get all the SOCGame data available; some games in getGameNames() may not have associated SOCGame data, so this enumeration may have fewer elements than getGameNames() or even 0 elements.
boolean	isGame(java.lang.String gaName) does this game exist in our list?
boolean	isUnjoinableGame(java.lang.String gaName) does this game have the unjoinable flag, either in its game info in our GameList, or by a special prefix in its name string?
java.util.Map<java.lang.String,SOCGameOption>	parseGameOptions(java.lang.String gaName) Parse these game options from string to map.
void	releaseMonitor() release the monitor for this game list
boolean	releaseMonitorForGame(java.lang.String game) Release the monitor for this game, recently taken by takeMonitorForGame(String).
int	size() Get the size (number of games) in our list.
void	takeMonitor() take the monitor for this game list; if we must wait, sleep up to 1000 ms between attempts.
boolean	takeMonitorForGame(java.lang.String game) take the monitor for this game.

Methods inherited from class java.lang.Object

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

Field Detail

gameInfo

protected java.util.Hashtable<java.lang.String,SOCGameList.GameInfo> gameInfo

key = String, value = SOCGameList.GameInfo; includes mutexes to synchronize game state access, game options, and other per-game info

gameData

protected java.util.Hashtable<java.lang.String,SOCGame> gameData

synchronized map of game names to SOCGame objects

inUse

protected boolean inUse

used with gamelist's monitor

Constructor Detail

SOCGameList

public SOCGameList()

constructor

Method Detail

takeMonitor

public void takeMonitor()

take the monitor for this game list; if we must wait, sleep up to 1000 ms between attempts.

releaseMonitor

public void releaseMonitor()

release the monitor for this game list

takeMonitorForGame

public boolean takeMonitorForGame(java.lang.String game)

take the monitor for this game. When done with it, you must call releaseMonitorForGame(String).

Parameters:

game - the name of the game

Returns:

false if the game has no mutex, or game not found in the list, or SOCGameList.GameInfo.gameDestroyed is true

releaseMonitorForGame

public boolean releaseMonitorForGame(java.lang.String game)

Release the monitor for this game, recently taken by takeMonitorForGame(String).

Release is allowed even if SOCGameList.GameInfo.gameDestroyed is true.

Parameters:

game - the name of the game

Returns:

false if the game has no mutex

getGameNames

public java.util.Set<java.lang.String> getGameNames()

Get the names of every game we know about, even those with no SOCGame object.

Returns:

an set of game names (Strings)

Since:

2.0.00

See Also:

getGamesData()

getGamesData

public java.util.Collection<SOCGame> getGamesData()

Get all the SOCGame data available; some games in getGameNames() may not have associated SOCGame data, so this enumeration may have fewer elements than getGameNames() or even 0 elements.

Returns:

an enumeration of game data (SOCGames)

Since:

1.1.06

See Also:

getGameNames()

size

public int size()

Get the size (number of games) in our list.

Returns:

the number of games in our list

Since:

1.1.07

getGameData

public SOCGame getGameData(java.lang.String gaName)

get a game's SOCGame, if we've stored that

Parameters:

gaName - game name

Returns:

the game object data, or null

getGameOptions

public java.util.Map<java.lang.String,SOCGameOption> getGameOptions(java.lang.String gaName)

get a game's SOCGameOptions, if stored and parsed

Parameters:

gaName - game name

Returns:

the game options (map of SOCGameOption), or null if none or if unparsed

Since:

1.1.07

See Also:

getGameOptionsString(String), parseGameOptions(String)

getGameOptionsString

public java.lang.String getGameOptionsString(java.lang.String gaName)

get a game's SOCGameOptions, as a packed string

Parameters:

gaName - game name

Returns:

the game options string, or null if no packed version

Since:

1.1.07

See Also:

getGameOptions(String)

parseGameOptions

public java.util.Map<java.lang.String,SOCGameOption> parseGameOptions(java.lang.String gaName)

Parse these game options from string to map. Should not be called at client before any updates to "known options" are received from server. Calls SOCGameList.GameInfo.parseOptsStr().

Parameters:

gaName - game name

Returns:

the game options, or null if none

Since:

1.1.07

See Also:

getGameOptionsString(String)

isGame

public boolean isGame(java.lang.String gaName)

does this game exist in our list?

Parameters:

gaName - the name of the game

Returns:

true if the game exists

isUnjoinableGame

public boolean isUnjoinableGame(java.lang.String gaName)

does this game have the unjoinable flag, either in its game info in our GameList, or by a special prefix in its name string?

Parameters:

gaName - the name of the game; may be marked with the prefix SOCGames.MARKER_THIS_GAME_UNJOINABLE. Remember that the prefix is not stored as part of the game name in this list, so it's not necessary to add the prefix when calling this method about a game already in our list.

Returns:

true if the game is in our list marked as not joinable, or has the prefix

Since:

1.1.07

addGame

public void addGame(java.lang.String gaName,
                    java.lang.String gaOptsStr,
                    boolean cannotJoin)

Client-side - Add this game name, with game options. If a game already exists (per isGame(String)), at most clear its canJoin flag.

Server should instead call SOCGameListAtServer.createGame(String, String, String, Map, soc.server.GameHandler).

Parameters:

gaName - Name of added game; may be marked with the prefix SOCGames.MARKER_THIS_GAME_UNJOINABLE.

gaOptsStr - set of SOCGameOptions as packed by SOCGameOption.packOptionsToString(Map, boolean), or null. Game options should remain unparsed as late as possible.

cannotJoin - This game is unjoinable, even if its name doesn't start with the unjoinable prefix. gaName will be checked for the prefix regardless of cannotJoin's value.

Since:

1.1.07

addGame

protected void addGame(java.lang.String gaName,
                       java.util.Map<java.lang.String,SOCGameOption> gaOpts,
                       java.lang.String gaOptsStr,
                       boolean cannotJoin)

Internal use - Add this game name, with game options. If a game already exists (per isGame(String)), at most clear its canJoin flag. Supply gaOpts or gaOptsStr, not both.

Client should instead call addGame(String, String, boolean) because game options should remain unparsed as late as possible. Server should instead call SOCGameListAtServer.createGame(String, String, String, Map, soc.server.GameHandler).

Parameters:

gaName - Name of added game; may be marked with the prefix SOCGames.MARKER_THIS_GAME_UNJOINABLE.

gaOpts - Map of game options of added game, or null

gaOptsStr - set of SOCGameOptions as packed by SOCGameOption.packOptionsToString(Map, boolean), or null. Game options should remain unparsed as late as possible.

cannotJoin - This game is unjoinable, even if its name doesn't start with the unjoinable prefix. gaName will be checked for the prefix regardless of cannotJoin's value.

Since:

1.1.07

See Also:

addGames(SOCGameList, int), addGames(Iterable, int)

addGames

public void addGames(SOCGameList gl,
                     int ourVersion)

Add the contents of another GameList to this GameList. Calls addGame for each one. gl's SOCGames will be added first, followed by games for which we only know the name and options.

For use at client. Each added game's SOCGameList.GameInfo is examined for game options and canJoin flag, but not directly copied.

Parameters:

gl - Another SOCGameList from which to copy game data. If gl is null, nothing happens. If any game already exists here (per this.isGame(String)), don't overwrite it.

ourVersion - Version to check to see if we can join, same format as Version.versionNumber(). For each SOCGame in gl, SOCGame.getClientVersionMinRequired() will be called.

Since:

1.1.07

addGames

public void addGames(java.lang.Iterable<?> gamelist,
                     int ourVersion)

Add several games to this GameList. Calls addGame(String, Map, String, boolean) for each one.

For use at client.

Parameters:

gamelist - Enumeration of Strings and/or SOCGames (mix and match); game names may be marked with the prefix SOCGames.MARKER_THIS_GAME_UNJOINABLE. If gamelist is null, nothing happens. If any game already exists (per isGame(String)), don't overwrite it; at most, clear its canJoin flag.

ourVersion - Version to check to see if we can join, same format as Version.versionNumber(). For each SOCGame in gameList, SOCGame.getClientVersionMinRequired() will be called.

Since:

1.1.07

deleteGame

public void deleteGame(java.lang.String gaName)

Remove the game from the list and call SOCGame.destroyGame(). Set its mutex's SOCGameList.GameInfo.gameDestroyed flag.

Parameters:

gaName - the name of the game; should not be marked with any prefix.