soc.message
Class SOCLocalizedStrings

java.lang.Object
  soc.message.SOCMessage
      soc.message.SOCMessageMulti
          soc.message.SOCMessageTemplateMs
              soc.message.SOCLocalizedStrings

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, SOCMessageForGame

public class SOCLocalizedStrings
extends SOCMessageTemplateMs

Message from server for i18n localization of item types such as game options or scenarios, such as TYPE_GAMEOPT or TYPE_SCENARIO, or request from client to get localized strings for specific keys of certain item types.

This message is always about one string type. The meaning of the keys and their strings may differ per string type. For example, keys for TYPE_SCENARIO are the same as in SOCScenario and the server sends two strings per scenario, its short and long description.

Normally sent from the server when client needs all keys or some keys for a type; see type constant javadocs. For example: When joining a game with a scenario, the client needs strings for that scenario. When creating a new game, the client needs strings for all scenarios in order to read about them and maybe choose one. The server's message includes the string type such as TYPE_SCENARIO, the flags field, and then each key and its string(s) as described above.

This message is not commonly sent from client to server, which is included to allow clients to get localized strings for scenarios or gameopts newer than the client or changed since the client's release. The client's request includes the string type such as TYPE_SCENARIO, the flags field, and then any keys for which it wants localized strings, or an empty list if message also sets FLAG_REQ_ALL to request all items. The server's response is as described above, including all keys requested by the client. If a key isn't known at the server, in the response that key will be followed by MARKER_KEY_UNKNOWN instead of by its string(s).

The first element of SOCMessageTemplateMs.getParams() is a string type such as TYPE_GAMEOPT or TYPE_SCENARIO. This is followed by the integer flag field (hex string) which is removed from the list at the receiving end's parser. The rest of getParams() is organized according to the type; see type constant javadocs. Since getParams() can't contain empty strings, check contents for EMPTY.

Not a per-game message; SOCMessageTemplateMs.getGame() returns SOCMessage.GAME_NONE.

Robot clients don't need to know about or handle this message type, because they don't have a locale.

Introduced in 2.0.00; check client version against SOCStringManager.VERSION_FOR_I18N.

Since:

2.0.00

Author:

Jeremy D Monin <jeremy@nand.net>

See Also:

Serialized Form

Field Summary

static java.lang.String	EMPTY Symbol to represent a null or empty string value, because empty pa[] elements can't be parsed over the network.
static int	FLAG_REQ_ALL "Request all" flag, for client to request all items of a requested type.
static int	FLAG_SENT_ALL "Sent all of them" flag, for server's response when it has sent all known items of the string type requested by the client.
static int	FLAG_TYPE_UNKNOWN "Type is unknown" flag, for server's response when it doesn't recognize the string type requested by the client.
private int	flags Request or response flags such as FLAG_SENT_ALL.
static java.lang.String	MARKER_KEY_UNKNOWN "Key is unknown" marker token, for server's response when it doesn't have a localized string for the key requested by the client.
private static java.lang.String	MARKER_PREFIX First character of all MARKERs
private static long	serialVersionUID
static java.lang.String	TYPE_GAMEOPT Game Option localized names, for SOCGameOption.
static java.lang.String	TYPE_SCENARIO Game Scenario localized names and descriptions, for SOCScenario.

Fields inherited from class soc.message.SOCMessageTemplateMs

game, pa

Fields inherited from class soc.message.SOCMessage

ACCEPTOFFER, ADMINPING, ADMINRESET, AUTHREQUEST, BANKTRADE, BCASTTEXTMSG, BOARDLAYOUT, BOARDLAYOUT2, BOARDSPECIALEDGE, BUILDREQUEST, BUYCARDREQUEST, CANCELBUILDREQUEST, CHANGEFACE, CHANNELS, CHOOSEPLAYER, CHOOSEPLAYERREQUEST, CLEAROFFER, CLEARTRADEMSG, CREATEACCOUNT, DEBUGFREEPLACE, DELETECHANNEL, DELETEGAME, DEVCARDACTION, DEVCARDCOUNT, DICERESULT, DICERESULTRESOURCES, DISCARD, DISCARDREQUEST, DISCOVERYPICK, ENDTURN, FIRSTPLAYER, GAME_NONE, GAMEMEMBERS, GAMEOPTIONGETDEFAULTS, GAMEOPTIONGETINFOS, GAMEOPTIONINFO, GAMES, GAMESERVERTEXT, GAMESTATE, GAMESTATS, GAMESWITHOPTIONS, GAMETEXTMSG, IMAROBOT, INVENTORYITEMACTION, JOIN, JOINAUTH, JOINGAME, JOINGAMEAUTH, LARGESTARMY, LASTSETTLEMENT, LEAVE, LEAVEALL, LEAVEGAME, LEGALEDGES, LOCALIZEDSTRINGS, LONGESTROAD, MAKEOFFER, MEMBERS, messageType, MONOPOLYPICK, MOVEPIECE, MOVEPIECEREQUEST, MOVEROBBER, NEWCHANNEL, NEWGAME, NEWGAMEWITHOPTIONS, NEWGAMEWITHOPTIONSREQUEST, NULLMESSAGE, PICKRESOURCES, PICKRESOURCESREQUEST, PIECEVALUE, PLAYDEVCARDREQUEST, PLAYERELEMENT, PLAYERELEMENTS, PLAYERSTATS, POTENTIALSETTLEMENTS, PUTPIECE, REJECTCONNECTION, REJECTOFFER, REMOVEPIECE, RESETBOARDAUTH, RESETBOARDREJECT, RESETBOARDREQUEST, RESETBOARDVOTE, RESETBOARDVOTEREQUEST, RESOURCECOUNT, REVEALFOGHEX, ROBOTDISMISS, ROBOTJOINGAMEREQUEST, ROLLDICE, ROLLDICEPROMPT, ROLLDICEREQUEST, SCENARIOINFO, sep, sep_char, sep2, sep2_char, SERVERPING, SETPLAYEDDEVCARD, SETSEATLOCK, SETSPECIALITEM, SETTURN, SETUPDONE, SIMPLEACTION, SIMPLEREQUEST, SITDOWN, STARTGAME, STATUSMESSAGE, SVPTEXTMSG, TEXTMSG, TIMINGPING, TURN, UPDATEROBOTPARAMS, VERSION

Constructor Summary

private	SOCLocalizedStrings(java.util.List<java.lang.String> strs) Constructor for client to parse server's list of localized strings.
	SOCLocalizedStrings(java.lang.String type, int flags, java.util.List<java.lang.String> strs) Server-side constructor.

Method Summary

private static void	checkParams(java.lang.String type, java.util.List<java.lang.String> strs) Check parameter format.
int	getMinimumVersion() Minimum version where this message type is used.
boolean	isFlagSet(int flag) Is this flag bit set in the flags field?
static SOCLocalizedStrings	parseDataStr(java.util.List<java.lang.String> strs) Parse the command String list into a SOCLocalizedStrings message.
static java.lang.String	toCmd(java.lang.String type, int flags, java.util.List<java.lang.String> strs) Build the command string from a type and list of strings; used at server side.
static java.lang.String	toCmd(java.lang.String type, int flags, java.lang.String str) Build the command string from a type and single string key; used for requests from client side.

Methods inherited from class soc.message.SOCMessageTemplateMs

getGame, getParams, toCmd, toCmd, toString

Methods inherited from class soc.message.SOCMessage

arrayIntoStringBuf, enumIntoStringBuf, getClassNameShort, getMaximumVersion, getType, isSingleLineAndSafe, isSingleLineAndSafe, toMsg

Methods inherited from class java.lang.Object

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

Methods inherited from interface soc.message.SOCMessageForGame

getType

Field Detail

EMPTY

public static final java.lang.String EMPTY

Symbol to represent a null or empty string value, because empty pa[] elements can't be parsed over the network.

See Also:

Constant Field Values

TYPE_GAMEOPT

public static final java.lang.String TYPE_GAMEOPT

Game Option localized names, for SOCGameOption. After the string type at element 0, SOCMessageTemplateMs.getParams() contents are pairs of strings, each of which is a game option keyname and localized name.

See Also:

Constant Field Values

TYPE_SCENARIO

public static final java.lang.String TYPE_SCENARIO

Game Scenario localized names and descriptions, for SOCScenario.

From Client:

SOCMessageTemplateMs.getParams() is a list of scenario keys (sc.key field) for which the client is requesting localized strings. FLAG_REQ_ALL is not supported; to get updated strings or info for all scenarios, send SOCScenarioInfo instead.

From Server:

After the string type at element 0, SOCMessageTemplateMs.getParams() contents are triples of strings, each of which is a game scenario keyname, localized name, and optional localized long description or EMPTY. As with any string type, an unknown keyname is a pair of strings here (not a triple): keyname, MARKER_KEY_UNKNOWN.

If the client has requested specific scenario keynames for this type, the server replies with all known localized strings for those items. Items without localized strings will not be included in the reply. If none of the items are localized, server replies with an empty list with the FLAG_SENT_ALL flag.

See Also:

Constant Field Values

MARKER_PREFIX

private static final java.lang.String MARKER_PREFIX

First character of all MARKERs

See Also:

Constant Field Values

FLAG_TYPE_UNKNOWN

public static final int FLAG_TYPE_UNKNOWN

"Type is unknown" flag, for server's response when it doesn't recognize the string type requested by the client.

See Also:

Constant Field Values

FLAG_REQ_ALL

public static final int FLAG_REQ_ALL

"Request all" flag, for client to request all items of a requested type. This flag is sent with an empty string list. Not all string types support this flag.

See Also:

FLAG_SENT_ALL, Constant Field Values

FLAG_SENT_ALL

public static final int FLAG_SENT_ALL

"Sent all of them" flag, for server's response when it has sent all known items of the string type requested by the client. The client should not request any further items of that string type.

This flag can also be sent when no known items are available for a recognized string type; the server will send an empty list with this flag set.

See Also:

FLAG_REQ_ALL, Constant Field Values

MARKER_KEY_UNKNOWN

public static final java.lang.String MARKER_KEY_UNKNOWN

"Key is unknown" marker token, for server's response when it doesn't have a localized string for the key requested by the client.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

flags

private int flags

Request or response flags such as FLAG_SENT_ALL.

See Also:

isFlagSet(int)

Constructor Detail

SOCLocalizedStrings

public SOCLocalizedStrings(java.lang.String type,
                           int flags,
                           java.util.List<java.lang.String> strs)
                    throws java.lang.IllegalArgumentException

Server-side constructor. The server usually uses static toCmd(String, int, List) to send this message to clients, but the constructor is used with the Practice client's local server.

Parameters:

type - String type such as TYPE_SCENARIO; must pass SOCMessage.isSingleLineAndSafe(String). This constructor will prepend type to the strs list.

flags - Any flags such as FLAG_SENT_ALL, or 0

strs - the list of strings, organized in a type-specific way; see type constant javadocs. Each element must pass isSingleLineAndSafe(String, true): SOCMessage.sep2 characters are allowed, but SOCMessage.sep are not.

The list may be empty or null. Since this constructor builds an object and not a network message command, will not replace empty or null elements with EMPTY or "". The constructor will prepend type to the strs list, creating it if null.

If any string starts with MARKER_PREFIX, it must be a recognized marker: (MARKER_KEY_UNKNOWN) declared in this class.

Throws:

java.lang.IllegalArgumentException - If type or any element of strs fails SOCMessage.isSingleLineAndSafe(String).

SOCLocalizedStrings

private SOCLocalizedStrings(java.util.List<java.lang.String> strs)
                     throws java.lang.NumberFormatException

Constructor for client to parse server's list of localized strings. See class javadoc for interpreting contents of this message.

The flags field (for FLAG_SENT_ALL, FLAG_TYPE_UNKNOWN, etc) is parsed here and removed from the list of strings.

Parameters:

strs - String list; assumes caller has validated length >= 2 (type, flags).

Throws:

java.lang.NumberFormatException - if flags field isn't a valid hex number

Method Detail

isFlagSet

public final boolean isFlagSet(int flag)

Is this flag bit set in the flags field?

Parameters:

flag - A flag such as FLAG_SENT_ALL

Returns:

True if set

getMinimumVersion

public final int getMinimumVersion()

Minimum version where this message type is used. LOCALIZEDSTRINGS introduced in 2.0.00 for i18n localization.

Overrides:

getMinimumVersion in class SOCMessage

Returns:

Version number, 2000 for JSettlers 2.0.00.

parseDataStr

public static SOCLocalizedStrings parseDataStr(java.util.List<java.lang.String> strs)

Parse the command String list into a SOCLocalizedStrings message.

Parameters:

strs - the data list; length must be at least 1 to indicate the type

Returns:

a SOCLocalizedStrings message, or null if parsing errors

toCmd

public static java.lang.String toCmd(java.lang.String type,
                                     int flags,
                                     java.util.List<java.lang.String> strs)
                              throws java.lang.IllegalArgumentException

Build the command string from a type and list of strings; used at server side.

Parameters:

type - String type such as TYPE_SCENARIO; must pass SOCMessage.isSingleLineAndSafe(String).

flags - Any flags such as FLAG_SENT_ALL, or 0

strs - the list of strings, organized in a type-specific way; see type constant javadocs. Each element must pass isSingleLineAndSafe(String, true): SOCMessage.sep2 characters are allowed, but SOCMessage.sep are not.

The list may be empty or null. Empty or null elements in strs are automatically replaced here with EMPTY, but SOCMessageTemplateMs.getParams() will not automatically replace EMPTY with "" at the receiver.

If any string starts with MARKER_PREFIX, it must be a recognized marker: (MARKER_KEY_UNKNOWN) declared in this class.

Returns:

the command string

Throws:

java.lang.IllegalArgumentException - If type or any element of strs fails SOCMessage.isSingleLineAndSafe(String).

java.lang.NullPointerException - if strs is null

toCmd

public static java.lang.String toCmd(java.lang.String type,
                                     int flags,
                                     java.lang.String str)
                              throws java.lang.IllegalArgumentException,
                                     java.lang.NullPointerException

Build the command string from a type and single string key; used for requests from client side.

Parameters:

type - String type such as TYPE_SCENARIO; must pass SOCMessage.isSingleLineAndSafe(String).

flags - Any flags such as FLAG_SENT_ALL, or 0

str - String key being requested, with type-specific meaning; see type constant javadocs. Must pass isSingleLineAndSafe(String, true): SOCMessage.sep2 characters are allowed, but SOCMessage.sep are not. If any string starts with MARKER_PREFIX, it must be a recognized marker (MARKER_KEY_UNKNOWN) declared in this class.

Returns:

the command string

Throws:

java.lang.IllegalArgumentException - If type or str fails SOCMessage.isSingleLineAndSafe(String).

java.lang.NullPointerException - if str is null

checkParams

private static void checkParams(java.lang.String type,
                                java.util.List<java.lang.String> strs)
                         throws java.lang.IllegalArgumentException

Check parameter format. Used by toCmd(String, int, List) and SOCLocalizedStrings(String, int, List); see toCmd(..) for required format and thus the checks performed.

Throws:

java.lang.IllegalArgumentException