soc.client
Class SOCPlayerClient

java.lang.Object
  soc.client.SOCPlayerClient

public class SOCPlayerClient
extends java.lang.Object

Standalone client for connecting to the SOCServer. (For applet see SOCApplet.) Prompts for name and password, displays list of games and channels available. The actual game is played in a separate SOCPlayerInterface window.

If you want another connection port, you have to specify it as the "port" argument in the html source. If you run this as a stand-alone, you have to specify the port.

At startup or init, will try to connect to server via SOCPlayerClient.ClientNetwork.connect(String, int). See that method for more details.

There are three possible servers to which a client can be connected:

• A remote server, running on the other end of a TCP connection
• A local TCP server, for hosting games, launched by this client: localTCPServer
• A "practice game" server, not bound to any TCP port, for practicing locally against robots: practiceServer

At most, the client is connected to the practice server and one TCP server. Each game's SOCGame.isPractice flag determines which connection to use.

Once connected, messages from the server are processed in SOCPlayerClient.MessageTreater.treat(SOCMessage, boolean).

Author:

Robert S Thomas

Nested Class Summary

static class	SOCPlayerClient.ClientNetwork Helper object to encapsulate and deal with network connectivity.
private static class	SOCPlayerClient.ClientWindowAdapter React to windowOpened, windowClosing events for GameAwtDisplay's Frame.
static class	SOCPlayerClient.GameAwtDisplay A SOCPlayerClient.GameDisplay implementation for AWT.
static interface	SOCPlayerClient.GameDisplay A facade for the SOCPlayerClient to use to invoke actions in the GUI
static class	SOCPlayerClient.GameManager Nested class for processing outgoing messages (putting).
private static class	SOCPlayerClient.GameOptionDefaultsTimeoutTask TimerTask used when new game is asked for, to prevent waiting forever for game option defaults.
private static class	SOCPlayerClient.GameOptionsTimeoutTask TimerTask used soon after client connect, to prevent waiting forever for game options info (assume slow connection or server bug).
private class	SOCPlayerClient.MessageTreater Nested class for processing incoming messages (treating).

Field Summary

private java.util.Map<java.lang.String,PlayerClientListener>	clientListeners Map from game-name to the listener for that game.
(package private) java.util.Locale	cliLocale Locale for i18n message lookups used for strings.
java.lang.String	DEFAULT_PRACTICE_GAMENAME For practice games, default game name ("Practice").
private SOCPlayerClient.GameDisplay	gameDisplay Display for all user interface, including and beyond games.
private SOCPlayerClient.GameManager	gameManager Helper object to send outgoing network traffic to the server.
protected static java.lang.String	GAMENAME_PREFIX_CANNOT_JOIN text prefix to show games this client cannot join.
protected java.util.Hashtable<java.lang.String,SOCGame>	games the games we're currently playing
protected java.util.Map<java.lang.String,java.lang.String>	gamesUnjoinableOverride the unjoinable game names from serverGames that player has asked to join, and been told they can't.
protected boolean	gotPassword true if we've stored the password and the server's replied that it's correct
protected java.util.Vector<java.lang.String>	ignoreList the ignore list
static boolean	isJavaOnOSX For use in password fields, and possibly by other places, detect if we're running on Mac OS X.
protected boolean	isNGOFWaitingForAuthStatus true if user clicked "new game" and, before showing NewGameOptionsFrame, we've sent the nickname (username) and password to the server and are waiting for a response.
protected int	lastFaceChange face ID chosen most recently (for use in new games)
private SOCPlayerClient.ClientNetwork	net Helper object to deal with network connectivity.
protected java.lang.String	nickname the nickname; null until validated and set by getValidNickname(true)
protected int	numPracticeGames Number of practice games started; used for naming practice games
protected java.lang.String	password the password for nickname.
protected ServerGametypeInfo	practiceServGameOpts Track the game options available at the remote server, at the practice server.
protected SOCGameList	serverGames all announced game names on the remote server, including games which we can't join due to limitations of the client.
protected SOCServerFeatures	sFeatures Server's active optional features, sent soon after connect, or null if unknown.
private SOCStringManager	strings i18n text strings in our cliLocale.
protected int	sVersion Server version number for remote server, sent soon after connect, 0 if no server, or -1 if version unknown.
protected ServerGametypeInfo	tcpServGameOpts Track the game options available at the remote server, at the practice server.
private SOCPlayerClient.MessageTreater	treater Helper object to receive incoming network traffic from the server.

Constructor Summary

SOCPlayerClient()
Create a SOCPlayerClient connecting to localhost port SOCPlayerClient.ClientNetwork.SOC_PORT_DEFAULT.

Method Summary

void	addToGameList(java.lang.String gameName, java.lang.String gameOptsStr, boolean addToSrvList) Add a new game to the initial window's list of games, and possibly to the server games list.
protected void	addToIgnoreList(java.lang.String name) add this name to the ignore list
protected void	checkGameoptsForUnknownScenario(java.util.Map<java.lang.String,SOCGameOption> opts) Check these game options to see if they contain a scenario we don't yet have full info about.
void	connect(java.lang.String chost, int cport, java.lang.String cuser, java.lang.String cpass) Connect and give feedback by showing MESSAGE_PANEL.
void	dispose() network trouble; if possible, ask if they want to play locally (practiceServer vs.
SOCPlayerClient.GameManager	getGameManager()
SOCPlayerClient.ClientNetwork	getNet()
java.lang.String	getNickname()
int	getServerVersion(SOCGame game) Server version, for checking feature availability.
void	leaveChannel(java.lang.String ch) the user leaves the given channel
protected void	localizeGameScenarios(java.util.List<java.lang.String> scStrs, boolean skipFirst, boolean sentAll, boolean isPractice) Localize SOCScenario names and descriptions with strings from the server.
static void	main(java.lang.String[] args) for stand-alones
protected boolean	onIgnoreList(java.lang.String name)
protected void	removeFromIgnoreList(java.lang.String name) remove this name from the ignore list
void	setGameDisplay(SOCPlayerClient.GameDisplay gd) Set our game display interface.
void	startPracticeGame() Create a game name, and start a practice game.
void	startPracticeGame(java.lang.String practiceGameName, java.util.Map<java.lang.String,SOCGameOption> gameOpts, boolean mainPanelIsActive) Setup for practice game (on the non-tcp server).
void	updateGameEndStats(java.lang.String game, int[] scores) If we're playing in a game that's just finished, update the scores.
static void	usage() for stand-alones
(package private) boolean	wantsI18nStrings(boolean isPractice) Should this client request localized strings (I18N) from the server if available? Checks server version, checks whether client locale differs from the fallback "en_US".

Methods inherited from class java.lang.Object

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

Field Detail

strings

private final SOCStringManager strings

i18n text strings in our cliLocale.

Since:

2.0.00

GAMENAME_PREFIX_CANNOT_JOIN

protected static final java.lang.String GAMENAME_PREFIX_CANNOT_JOIN

text prefix to show games this client cannot join. "(cannot join) "

Since:

1.1.06

See Also:

Constant Field Values

isJavaOnOSX

public static final boolean isJavaOnOSX

For use in password fields, and possibly by other places, detect if we're running on Mac OS X. To identify osx from within java, see technote TN2110: http://developer.apple.com/technotes/tn2002/tn2110.html

Since:

1.1.07

cliLocale

final java.util.Locale cliLocale

Locale for i18n message lookups used for strings. Also sent to server while connecting. Override if needed in the constructor by reading the PROP_JSETTLERS_LOCALE system property "jsettlers.locale".

Since:

2.0.00

net

private SOCPlayerClient.ClientNetwork net

Helper object to deal with network connectivity.

treater

private SOCPlayerClient.MessageTreater treater

Helper object to receive incoming network traffic from the server.

gameManager

private SOCPlayerClient.GameManager gameManager

Helper object to send outgoing network traffic to the server.

gameDisplay

private SOCPlayerClient.GameDisplay gameDisplay

Display for all user interface, including and beyond games.

sVersion

protected int sVersion

Server version number for remote server, sent soon after connect, 0 if no server, or -1 if version unknown. A local practice server's version is always Version.versionNumber(), not sVersion, so always check SOCGame.isPractice before checking this field.

sFeatures

protected SOCServerFeatures sFeatures

Server's active optional features, sent soon after connect, or null if unknown. Not used with a local practice server, so always check SOCGame.isPractice before checking this field.

Since:

1.1.19

See Also:

tcpServGameOpts

tcpServGameOpts

protected ServerGametypeInfo tcpServGameOpts

Track the game options available at the remote server, at the practice server. Initialized by SOCPlayerClient.GameAwtDisplay.gameWithOptionsBeginSetup(boolean, boolean) and/or SOCPlayerClient.MessageTreater.handleVERSION(boolean, SOCVersion). These fields are never null, even if the respective server is not connected or not running.

For a summary of the flags and variables involved with game options, and the client/server interaction about their values, see ServerGametypeInfo's javadoc.

Scenario strings are localized by localizeGameScenarios(List, boolean, boolean, boolean).

Since:

1.1.07

See Also:

sFeatures

practiceServGameOpts

protected ServerGametypeInfo practiceServGameOpts

Track the game options available at the remote server, at the practice server. Initialized by SOCPlayerClient.GameAwtDisplay.gameWithOptionsBeginSetup(boolean, boolean) and/or SOCPlayerClient.MessageTreater.handleVERSION(boolean, SOCVersion). These fields are never null, even if the respective server is not connected or not running.

For a summary of the flags and variables involved with game options, and the client/server interaction about their values, see ServerGametypeInfo's javadoc.

Scenario strings are localized by localizeGameScenarios(List, boolean, boolean, boolean).

Since:

1.1.07

See Also:

sFeatures

DEFAULT_PRACTICE_GAMENAME

public final java.lang.String DEFAULT_PRACTICE_GAMENAME

For practice games, default game name ("Practice"). Set in constructor using i18n strings lookup.

nickname

protected java.lang.String nickname

the nickname; null until validated and set by getValidNickname(true)

password

protected java.lang.String password

the password for nickname. If the server's authenticated this password, the gotPassword flag is set.

gotPassword

protected boolean gotPassword

true if we've stored the password and the server's replied that it's correct

See Also:

isNGOFWaitingForAuthStatus

isNGOFWaitingForAuthStatus

protected boolean isNGOFWaitingForAuthStatus

true if user clicked "new game" and, before showing NewGameOptionsFrame, we've sent the nickname (username) and password to the server and are waiting for a response.

Used only with TCP servers, not with practiceServer.

Since:

1.1.19

lastFaceChange

protected int lastFaceChange

face ID chosen most recently (for use in new games)

games

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

the games we're currently playing

serverGames

protected SOCGameList serverGames

all announced game names on the remote server, including games which we can't join due to limitations of the client. May also contain options for all announced games on the server (not just ones we're in) which we can join (version is not higher than our version).

Key is the game name, without the UNJOINABLE prefix. This field is null until handleGAMES, handleGAMESWITHOPTIONS, handleNEWGAME or handleNEWGAMEWITHOPTIONS is called.

Since:

1.1.07

gamesUnjoinableOverride

protected java.util.Map<java.lang.String,java.lang.String> gamesUnjoinableOverride

the unjoinable game names from serverGames that player has asked to join, and been told they can't. If they click again, try to connect. (This is a failsafe against bugs in server or client version-recognition.) Both key and value are the game name, without the UNJOINABLE prefix.

Since:

1.1.06

clientListeners

private final java.util.Map<java.lang.String,PlayerClientListener> clientListeners

Map from game-name to the listener for that game.

ignoreList

protected java.util.Vector<java.lang.String> ignoreList

the ignore list

numPracticeGames

protected int numPracticeGames

Number of practice games started; used for naming practice games

Constructor Detail

SOCPlayerClient

public SOCPlayerClient()

Create a SOCPlayerClient connecting to localhost port SOCPlayerClient.ClientNetwork.SOC_PORT_DEFAULT. Initializes helper objects (except SOCPlayerClient.GameDisplay), locale, SOCStringManager. The locale will be the current user's default locale, unless overridden by setting the PROP_JSETTLERS_LOCALE system property "jsettlers.locale".

Must call SOCApplet.init(), or setGameDisplay(GameDisplay) and then SOCPlayerClient.GameDisplay.initVisualElements(), to start up and do layout.

Must then call connect(String, int, String, String) or SOCPlayerClient.ClientNetwork.connect(String, int) to join a TCP server, or SOCPlayerClient.GameDisplay.clickPracticeButton() or SOCPlayerClient.GameAwtDisplay.startLocalTCPServer(int) to start a server locally.

Method Detail

setGameDisplay

public void setGameDisplay(SOCPlayerClient.GameDisplay gd)

Set our game display interface. Before using the client, caller must also call SOCPlayerClient.GameDisplay.initVisualElements().

Since:

2.0.00

connect

public void connect(java.lang.String chost,
                    int cport,
                    java.lang.String cuser,
                    java.lang.String cpass)

Connect and give feedback by showing MESSAGE_PANEL. Calls SOCPlayerClient.GameDisplay.connect(String, String) to set username and password, then SOCPlayerClient.ClientNetwork.connect(String, int) to make the connection.

Parameters:

chost - Hostname to connect to, or null for localhost

cport - Port number to connect to

cuser - User nickname

cpass - User optional password

getNickname

public java.lang.String getNickname()

Returns:

the nickname of this user

See Also:

SOCPlayerClient.GameAwtDisplay.getValidNickname(boolean)

wantsI18nStrings

final boolean wantsI18nStrings(boolean isPractice)

Should this client request localized strings (I18N) from the server if available? Checks server version, checks whether client locale differs from the fallback "en_US".

Parameters:

isPractice - True if checking for local practice server, not a remote server

Returns:

True if client should request localized strings

Since:

2.0.00

checkGameoptsForUnknownScenario

protected void checkGameoptsForUnknownScenario(java.util.Map<java.lang.String,SOCGameOption> opts)

Check these game options to see if they contain a scenario we don't yet have full info about. If the options include a scenario and we don't have that scenario's info or localized strings, ask the server for that but don't wait here for a reply.

Do not call for practice games: Assumes this is the TCP server, because for practice games we already have full info about scenarios and their strings.

Parameters:

opts - Game options to check for "SC", or null

Since:

2.0.00

localizeGameScenarios

protected void localizeGameScenarios(java.util.List<java.lang.String> scStrs,
                                     boolean skipFirst,
                                     boolean sentAll,
                                     boolean isPractice)

Localize SOCScenario names and descriptions with strings from the server. Updates scenario data in practiceServGameOpts or tcpServGameOpts.

Parameters:

scStrs - Scenario localized strings, same format as SOCLocalizedStrings params.

skipFirst - If true skip the first element of scStrs, it isn't a scenario keyname.

sentAll - True if no further strings will be received; is SOCLocalizedStrings.FLAG_SENT_ALL set? If true, sets ServerGametypeInfo.allScenStringsReceived.

isPractice - Is the server SOCPlayerClient.ClientNetwork.practiceServer, not remote?

Since:

2.0.00

addToGameList

public void addToGameList(java.lang.String gameName,
                          java.lang.String gameOptsStr,
                          boolean addToSrvList)

Add a new game to the initial window's list of games, and possibly to the server games list.

Parameters:

gameName - the game name to add to the list; may have the prefix SOCGames.MARKER_THIS_GAME_UNJOINABLE

gameOptsStr - String of packed game options, or null

addToSrvList - Should this game be added to the list of remote-server games? Practice games should not be added. The serverGames list also has a flag for cannotJoin.

See Also:

SOCPlayerClient.GameDisplay.addToGameList(boolean, String, String, boolean)

updateGameEndStats

public void updateGameEndStats(java.lang.String game,
                               int[] scores)

If we're playing in a game that's just finished, update the scores. This is used to show the true scores, including hidden victory-point cards, at the game's end.

leaveChannel

public void leaveChannel(java.lang.String ch)

the user leaves the given channel

Parameters:

ch - the name of the channel

getGameManager

public SOCPlayerClient.GameManager getGameManager()

onIgnoreList

protected boolean onIgnoreList(java.lang.String name)

Returns:

true if name is on the ignore list

addToIgnoreList

protected void addToIgnoreList(java.lang.String name)

add this name to the ignore list

Parameters:

name - the name to add

removeFromIgnoreList

protected void removeFromIgnoreList(java.lang.String name)

remove this name from the ignore list

Parameters:

name - the name to remove

startPracticeGame

public void startPracticeGame()

Create a game name, and start a practice game. Assumes SOCPlayerClient.GameAwtDisplay.MAIN_PANEL is initialized.

startPracticeGame

public void startPracticeGame(java.lang.String practiceGameName,
                              java.util.Map<java.lang.String,SOCGameOption> gameOpts,
                              boolean mainPanelIsActive)

Setup for practice game (on the non-tcp server). If needed, a (stringport, not tcp) SOCPlayerClient.ClientNetwork.practiceServer, client, and robots are started.

Parameters:

practiceGameName - Unique name to give practice game; if name unknown, call startPracticeGame() instead

gameOpts - Set of game options to use, or null

mainPanelIsActive - Is the SOCPlayerClient main panel active? False if we're being called from elsewhere, such as SOCConnectOrPracticePanel.

getServerVersion

public int getServerVersion(SOCGame game)

Server version, for checking feature availability. Returns -1 if unknown.

Parameters:

game - Game being played on a practice or tcp server.

Returns:

Server version, format like Version.versionNumber(), or 0 or -1.

dispose

public void dispose()

network trouble; if possible, ask if they want to play locally (practiceServer vs. robots). Otherwise, go ahead and shut down.

usage

public static void usage()

for stand-alones

main

public static void main(java.lang.String[] args)

for stand-alones

getNet

public SOCPlayerClient.ClientNetwork getNet()