soc.message
Class SOCScenarioInfo

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

All Implemented Interfaces:

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

public class SOCScenarioInfo
extends SOCMessageTemplateMs

A client's request for updated SOCScenario info, or server's reply with information on one available SOCScenario (including localization). This is so clients can get localization; or find out about scenarios which were introduced in versions newer than the client's version, but which may be usable at their version or all versions; or ask an older server what it knows about scenario(s) changed since the server's version.

Timing:

When client connects, it doesn't yet need any scenario information. At that point the client will request any added, changed, or localized SOCGameOptions. This early game option sync guarantees that when the client later needs any scenario info, it already knows about any options listed in SOCScenario.scOpts. The server will also know from this if the client wants localized strings in general.

Get Game Info: If the user clicks the Game Info button for a game with a scenario, at that point the client can send a SOCScenarioInfo message to request info about that scenario.

Join Game: If the user joins a game with a scenario, before SOCJoinGameAuth the server can send a SOCScenarioInfo or SOCLocalizedStrings message with info about that scenario if needed.

New Game: When the user wants to create a new game, the client should send a SOCScenarioInfo to request all updated info for scenarios; the server and client synchronize SOCScenario info at this point.

Client request to Server:

The client can request information about a single scenario (for the Game Info button), or request all new or changed scenarios when client and server are different versions or locales.

• For a single scenario, the client request's parameter list has 1 item, the scenario's SOCScenario.key.
• If client is older than server, the request's list has 1 item, MARKER_ANY_CHANGED. Server should calculate and send all scenarios changed/added since the client's version.
• If client is newer than server, client should calculate any scenarios it knows about which are new or changed since the older server's version. The parameter list will have all of those, and end with MARKER_ANY_CHANGED so the server knows to end its reply sequence with a message having the noMoreScens flag. The server's reply sequence will have a message about each scenario key in the client's request.
• If client and server are the same version, and client only wants localized i18n scenario strings, client sends SOCScenarioInfo with 1 item, MARKER_ANY_CHANGED.

This scenario info sync protocol for different versions is very similar to that done for SOCGameOptions at client connect with SOCGameOptionGetInfos/SOCGameOptionInfo. The list can be calculated with SOCVersionedItem.itemsNewerThanVersion(int, boolean, java.util.Map).

I18N: Because client has previously sent SOCGameOptionGetInfos if needed, the server knows whether the client wants localized strings, so SOCScenarioInfo has no i18n flag like SOCGameOptionGetInfos.OPTKEY_GET_I18N_DESCS.

Server reply to client:

There are two message types which may send scenario info to the client:

• If the client is a different version than the server, a sequence of SOCScenarioInfo messages sends all info about new or changed scenarios, including those scenarios' localized text. The sequence ends with a message which has the noMoreScens flag.

  Any scenarios too new for the client (per sc.minVersion) are included in the sequence with the isKeyUnknown flag, in case the client encounters them as a listed game's scenario. This is consistent with how too-new SOCGameOptions are sent to clients.

  Separately, a single SOCScenarioInfo can be sent when the client requests info on that scenario or asks to join a game with a scenario not previously sent to the client.

• If the client is a different locale than the server, a single SOCLocalizedStrings message can send all scenarios' localized text if available. If the client was sent SOCScenarioInfo about a given scenario, it won't also get SOCLocalizedStrings for the same scenario. See SOCLocalizedStrings javadoc for more information about that message type.

The server's SOCScenarioInfo reply message provides the scenario's information, including public fields with game options and description localized for the client, and sets these flags/fields:

• getScenario(), all scenario details if available
• getScenarioKey(), the key for a scenario requested by the client
• isKeyUnknown if the server doesn't know a scenario requested by the client
• noMoreScens if this is an empty message marking the end of the reply sequence

Special case: If the client is asking for any new or changed scenarios but there aren't any, server responds with a single SOCScenarioInfo with the noMoreScens flag.

Introduced in 2.0.00; check receiver's version against SOCScenario.VERSION_FOR_SCENARIOS before sending this message.

Robot clients don't need to know about or handle this message type, because they are always the server's version and thus know about the same scenarios.

Since:

2.0.00

Author:

Jeremy D Monin <jeremy@nand.net>

See Also:

Serialized Form

Field Summary

private static java.lang.String	EMPTYSTR Symbol to represent a null or empty string value, because empty pa[] elements can't be parsed.
boolean	isKeyUnknown If true, this requested getScenarioKey() is unknown; used in reply from server to client.
static java.lang.String	MARKER_ANY_CHANGED scKey marker "?" from client to ask for any new or changed scenarios between the client and server versions.
static int	MARKER_KEY_UNKNOWN Marker to indicate the requested scenario key is unknown.
static java.lang.String	MARKER_NO_MORE_SCENS scKey marker "-" from server to indicate this is the end of the list of SCENARIOINFOs.
boolean	noMoreScens If true, there are no more scenarios to send; used in reply from server to client.
private SOCScenario	sc Parsed scenario from server (getScenario()), or null if isKeyUnknown or noMoreScens or if this message is from client to server.
static SOCScenarioInfo	SCENINFO_NO_MORE_SCENS If an older client is asking for any changed/new scenarios, server responds with set of SCENARIOINFOs.
private java.lang.String	scKey The scenario key in a reply from server.
private static long	serialVersionUID

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	SOCScenarioInfo(java.util.List<java.lang.String> pa) Constructor to parse an incoming message; see parseDataStr(List) for expected pa format.
	SOCScenarioInfo(java.util.List<java.lang.String> scKeys, boolean addMarkerAnyChanged) Constructor for client to ask a server for info about any new or changed scenarios and/or about specific scenario keys.
	SOCScenarioInfo(SOCScenario sc, java.lang.String localDesc, java.lang.String localLongDesc) Constructor for server to tell client about a scenario, or mark the end of the list of scenarios.
	SOCScenarioInfo(java.lang.String scKey, boolean isServerReply) Constructor for client to ask the server for info about a single scenario, or for server to tell client that a requested scenario is unknown.

Method Summary

int	getMinimumVersion() Minimum version where this message type is used.
SOCScenario	getScenario() The scenario info, if any.
java.lang.String	getScenarioKey() The scenario keyname this message is about.
static SOCScenarioInfo	parseDataStr(java.util.List<java.lang.String> pa) Parse the parameter list into a SOCScenarioInfo message.

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

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

SCENINFO_NO_MORE_SCENS

public static final SOCScenarioInfo SCENINFO_NO_MORE_SCENS

If an older client is asking for any changed/new scenarios, server responds with set of SCENARIOINFOs. Mark end of this list with a SCENARIOINFO named "-". At the client this sets the noMoreScens flag.

EMPTYSTR

private static final java.lang.String EMPTYSTR

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

See Also:

Constant Field Values

MARKER_ANY_CHANGED

public static final java.lang.String MARKER_ANY_CHANGED

scKey marker "?" from client to ask for any new or changed scenarios between the client and server versions. When present, this is the last item in the parameter list. The server will reply with a sequence of messages with scenario info, and a sequence-ending empty message with only the noMoreScens flag.

See Also:

Constant Field Values

MARKER_NO_MORE_SCENS

public static final java.lang.String MARKER_NO_MORE_SCENS

scKey marker "-" from server to indicate this is the end of the list of SCENARIOINFOs.

See Also:

Constant Field Values

MARKER_KEY_UNKNOWN

public static final int MARKER_KEY_UNKNOWN

Marker to indicate the requested scenario key is unknown. Sent from server as -2 in the reply's lastModVersion field.

See Also:

Constant Field Values

sc

private SOCScenario sc

Parsed scenario from server (getScenario()), or null if isKeyUnknown or noMoreScens or if this message is from client to server.

See Also:

scKey

scKey

private final java.lang.String scKey

The scenario key in a reply from server. If isKeyUnknown, use scKey because sc is null.

isKeyUnknown

public final boolean isKeyUnknown

If true, this requested getScenarioKey() is unknown; used in reply from server to client. This can occur if the client's version is newer than the server. A message with this flag set will have null getScenario().

noMoreScens

public final boolean noMoreScens

If true, there are no more scenarios to send; used in reply from server to client. A message with this flag set will have null getScenario().

Constructor Detail

SOCScenarioInfo

public SOCScenarioInfo(SOCScenario sc,
                       java.lang.String localDesc,
                       java.lang.String localLongDesc)

Constructor for server to tell client about a scenario, or mark the end of the list of scenarios.

Parameters:

sc - Scenario to send, or null to send the end-of-list marker SCENINFO_NO_MORE_SCENS. Scenario key isn't checked here for SOCMessage.isSingleLineAndSafe(String) because the SOCScenario constructor already checked it against more restrictive SOCVersionedItem.isAlphanumericUpcaseAscii(String).

localDesc - i18n localized brief description, or null to use SOCScenario.getDesc()

localLongDesc - i18n localized long description, or null to use SOCScenario.getLongDesc()

See Also:

SOCScenarioInfo(String, boolean), SOCScenarioInfo(List, boolean)

SOCScenarioInfo

public SOCScenarioInfo(java.lang.String scKey,
                       boolean isServerReply)
                throws java.lang.IllegalArgumentException

Constructor for client to ask the server for info about a single scenario, or for server to tell client that a requested scenario is unknown.

Parameters:

scKey - Keyname of a scenario, requested at client or unknown at server

isServerReply - True if replying from server, false if requesting from client

Throws:

java.lang.IllegalArgumentException - if scKey fails SOCMessage.isSingleLineAndSafe(String)

See Also:

SOCScenarioInfo(List, boolean), SOCScenarioInfo(SOCScenario, String, String)

SOCScenarioInfo

public SOCScenarioInfo(java.util.List<java.lang.String> scKeys,
                       boolean addMarkerAnyChanged)
                throws java.lang.IllegalArgumentException

Constructor for client to ask a server for info about any new or changed scenarios and/or about specific scenario keys.

Parameters:

scKeys - List of scenarios to ask about, or null for an empty list

addMarkerAnyChanged - If true, append MARKER_ANY_CHANGED to the sent list

Throws:

java.lang.IllegalArgumentException - if ! addMarkerAnyChanged and scKeys is null or empty (this would be an empty message), or if any element of scKeys fails SOCMessage.isSingleLineAndSafe(String)

See Also:

SOCScenarioInfo(String, boolean), SOCScenarioInfo(SOCScenario, String, String)

SOCScenarioInfo

private SOCScenarioInfo(java.util.List<java.lang.String> pa)
                 throws java.lang.IllegalArgumentException,
                        java.lang.IndexOutOfBoundsException,
                        java.lang.NumberFormatException

Constructor to parse an incoming message; see parseDataStr(List) for expected pa format. If message is from client, removes the SOCMessage.GAME_NONE first element.

Throws:

java.lang.IllegalArgumentException - if pa length < 5 from server or < 2 from client, or if message is from server and any field fails the SOCScenario.SOCScenario(String, int, int, String, String, String) constructor's requirements for it

java.lang.IndexOutOfBoundsException - if pa is empty or its only element is SOCMessage.GAME_NONE

java.lang.NumberFormatException - if any pa integer field's contents are incorrectly formatted.

Method Detail

getMinimumVersion

public int getMinimumVersion()

Minimum version where this message type is used. SCENARIOINFO introduced in 2.0.00.

Overrides:

getMinimumVersion in class SOCMessage

Returns:

Version number, 2000 for JSettlers 2.0.00

getScenario

public SOCScenario getScenario()

The scenario info, if any. Used in replies from server to client. If the isKeyUnknown or noMoreScens flag is set, this is null. getScenarioKey() will name the scenario and won't be null.

Returns:

the parsed scenario from server, or null if this message is coming from a client or if either flag is set.

getScenarioKey

public java.lang.String getScenarioKey()

The scenario keyname this message is about. Used in replies from server to client. If isKeyUnknown flag is true, this field is set but getScenario() is null.

Returns:

Key name of a scenario, from sc.key

parseDataStr

public static SOCScenarioInfo parseDataStr(java.util.List<java.lang.String> pa)

Parse the parameter list into a SOCScenarioInfo message.

From Client:

pa is a list of scenario keynames the client is requesting info about. pa[0] is the marker SOCMessage.GAME_NONE. List might end with MARKER_ANY_CHANGED.

From Server:

• pa[0] = key (name of the scenario)
• pa[1] = minimum version integer
• pa[2] = last-modified version integer
• pa[3] = game options if any, or "-", from SOCScenario.scOpts
• pa[4] = one-line description (displayed text), localized to client if localized text is available
• pa[5] if present = long description (paragraph of displayed text) if any, localized to client if available

SOCMessageTemplateMs has an optional SOCMessageTemplateMs.getGame() field in the message, which if non-null appears here as the first parameter in the string list. To determine if we're parsing a message from the client or from the server, note that messages from the client have getGame() == SOCMessage.GAME_NONE, those from the server have null and their first parameter is a scenario keyname instead. GAME_NONE is guaranteed to not be a valid scenario keyname; it contains a character not valid for scenario keys.

Parameters:

pa - the String parameters

Returns:

a SOCScenarioInfo message, or null if parsing errors