soc.message
Class SOCSetSpecialItem

java.lang.Object
  soc.message.SOCMessage
      soc.message.SOCSetSpecialItem

All Implemented Interfaces:

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

public class SOCSetSpecialItem
extends SOCMessage
implements SOCMessageForGame

This message is to pick, set, or clear a SOCSpecialItem in the game and/or owning player's Special Item list. Within the game data, items are held in per-game and/or per-player Special Item lists. The message conveys which object is affected (typeKey, gameItemIndex, playerItemIndex) and the object data fields (playerNumber, coord, level, sv). When a Special Item is held in the game's list and also its owning player's list, the message can update both lists at once.

A client player can request that a player or game Special Item list index be picked, set, or cleared. The server can decline that request, or announce a change or pick to all members of the game. The server can also send a SOCSetSpecialItem message when anything happens in-game that causes a change. If the special item change has also caused a change to game state, the server will announce that after sending the special item message(s).

In some scenarios, there may be a resource or other cost for picking, setting, or clearing an item. If so, the server will check whether the requesting player can pay, and if so, the SOCSetSpecialItem response message(s) from the server will be preceded by SOCPlayerElement messages reporting the player's losses to pay the cost.

If client joins the game after it starts, these messages will be sent after the SOCBoardLayout2 message. So, SOCGame.updateAtBoardLayout() will have been called at the client and created Special Item objects before any SOCSetSpecialItem is received.

For message traffic/protocol details see OP_SET, OP_CLEAR, OP_PICK and OP_DECLINE javadocs; client requests typically use OP_PICK. For game details see the SOCSpecialItem class javadoc.

Since:

2.0.00

Author:

Jeremy D Monin <jeremy@nand.net>

See Also:

Serialized Form

Field Summary

int	coord Optional coordinates on the board for this item, or -1.
static java.lang.String	EMPTYSTR Symbol to represent a null or empty string value, because empty pa[] elements can't be parsed over the network with the current tokenizer.
java.lang.String	game Name of game.
int	gameItemIndex Index in the game's Special Item list, or -1.
int	level Optional level of construction or strength, or 0.
int	op The operation code: OP_SET, OP_CLEAR, OP_PICK or OP_DECLINE.
static int	OP_CLEAR If sent from client to server, a request to clear an item in the game and/or owning player's Special Item list.
static int	OP_DECLINE Sent from server as reply to a requesting client's OP_SET, OP_CLEAR, or OP_PICK: The client's request is declined.
static int	OP_PICK If sent from client to server, a request to pick or choose an item for some action.
static int	OP_SET If sent from client to server, a request to set an item in the game and/or owning player's Special Item list.
private static java.lang.String[]	OPS_STRS OP_* constant strings for toString()
int	playerItemIndex Index in the owning player's Special Item list, or -1.
int	playerNumber Owning player number, or -1.
private static long	serialVersionUID
java.lang.String	sv Optional string value from SOCSpecialItem.getStringValue(), or null.
java.lang.String	typeKey Special item type key; see the SOCSpecialItem class javadoc for details.

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

SOCSetSpecialItem(SOCGame game, int op, java.lang.String typeKey, int gi, int pi, SOCSpecialItem item)
Create a SOCSetSpecialItem message with data fields from an item object.

SOCSetSpecialItem(java.lang.String ga, int op, java.lang.String typeKey, int gi, int pi, int pn)
Create a SOCSetSpecialItem message, specifying all field values except coordinate (-1), level (0), stringValue (null).

SOCSetSpecialItem(java.lang.String ga, int op, java.lang.String typeKey, int gi, int pi, int pn, int co, int lv, java.lang.String sv)
Create a SOCSetSpecialItem message, specifying all field values.

Method Summary

java.lang.String	getGame() Name of game this message is for.
int	getMinimumVersion() Minimum version where this message type is used.
static SOCSetSpecialItem	parseDataStr(java.lang.String s) Parse the command String into a SOCSetSpecialItem message.
java.lang.String	toCmd() SETSPECIALITEM sep game sep2 operation sep2 typeKey sep2 gameItemIndex sep2 playerItemIndex sep2 playerNumber sep2 coord sep2 level sep2 sv
java.lang.String	toString() Simple human-readable representation, used for debug purposes.

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

EMPTYSTR

public static final java.lang.String EMPTYSTR

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

See Also:

Constant Field Values

OP_SET

public static final int OP_SET

If sent from client to server, a request to set an item in the game and/or owning player's Special Item list.

If sent from server to client(s) because of something in game or responding to a client request, this item will be set.

If gameItemIndex != -1, sets the special item's SOCSpecialItem.getGameIndex(), otherwise will not clear or change that field.

If setting for both the game and the owning player (gameItemIndex != -1 and playerItemIndex != -1), the client will check the game for an existing object before checking the player. That is: If the game and player previously had different objects (not null) at the specified special item indices, now they will both have a reference to the game's object. If the game's list item at this index was null, the player's object will now also be referenced in the game's Special Item list.

OP_SET is the lowest-numbered operation.

See Also:

Constant Field Values

OP_CLEAR

public static final int OP_CLEAR

If sent from client to server, a request to clear an item in the game and/or owning player's Special Item list.

If sent from server to client(s) because of something in game or in response to a client request, this item will be cleared.

See Also:

Constant Field Values

OP_PICK

public static final int OP_PICK

If sent from client to server, a request to pick or choose an item for some action.

If sent from server to client(s), this item has been picked for some action. The server isn't required to announce the pick to all players, only to the requesting player. Depending on the situation in which the item is being picked, it may or may not make sense to announce it. For clarity, any change to the contents of a Special Item list must be done with OP_SET or OP_CLEAR, never implied by sending only OP_PICK.

Alternately, the server will respond to the requesting player with OP_DECLINE.

The sequence of messages sent from the server for a player's successful PICK are:

1. SOCPlayerElement message(s) to pay the cost, if any
2. OP_SET or OP_CLEAR message(s) resulting from the pick
3. OP_PICK itself
4. SOCGameState and related messages, if the state changed or the game is now over

For convenience, the server's PICK message includes the coord, level, and sv field values of the special item being picked. Different scenarios might change picked objects in different ways, so these fields are filled by:

• If the pick causes the item to become null and be cleared, the values before the pick as retrieved by SOCGame.getSpecialItem(String, int, int, int)
• Otherwise, the field values after the pick
• If the pick specifies both gameItemIndex and playerItemIndex, and afterwards these are two different SOCSpecialItem objects, then the values are taken from gameItemIndex's item if not null, otherwise from playerItemIndex's item.

When the client receives the PICK, they can get the field values if needed by calling SOCGame.getSpecialItem(String, int) or SOCPlayer.getSpecialItem(String, int), because the SET or CLEAR messages are sent out before the PICK.

OP_PICK is currently the highest-numbered operation that a client can send as a request.

See Also:

Constant Field Values

OP_DECLINE

public static final int OP_DECLINE

Sent from server as reply to a requesting client's OP_SET, OP_CLEAR, or OP_PICK: The client's request is declined.

The reply's data fields (typeKey, gameItemIndex, etc) will have the same values as the request.

See Also:

Constant Field Values

game

public final java.lang.String game

Name of game.

typeKey

public final java.lang.String typeKey

Special item type key; see the SOCSpecialItem class javadoc for details.

op

public final int op

The operation code: OP_SET, OP_CLEAR, OP_PICK or OP_DECLINE.

gameItemIndex

public final int gameItemIndex

Index in the game's Special Item list, or -1.

playerItemIndex

public final int playerItemIndex

Index in the owning player's Special Item list, or -1. If used, playerNumber must be != -1.

playerNumber

public final int playerNumber

Owning player number, or -1. The item doesn't need to be in the owner's Special Item list; if it should be, set playerItemIndex. A player can only request with their own playerNumber, server ignores this field.

coord

public final int coord

Optional coordinates on the board for this item, or -1. An edge or a node, depending on item type.

level

public final int level

Optional level of construction or strength, or 0.

sv

public final java.lang.String sv

Optional string value from SOCSpecialItem.getStringValue(), or null.

OPS_STRS

private static final java.lang.String[] OPS_STRS

OP_* constant strings for toString()

Constructor Detail

SOCSetSpecialItem

public SOCSetSpecialItem(SOCGame game,
                         int op,
                         java.lang.String typeKey,
                         int gi,
                         int pi,
                         SOCSpecialItem item)
                  throws java.lang.IllegalArgumentException,
                         java.lang.NullPointerException

Create a SOCSetSpecialItem message with data fields from an item object.

Parameters:

game - game; only its name is used in this message

op - Operation code: see op for values

typeKey - Special item type key; see the SOCSpecialItem class javadoc for details

gi - Game item index, or -1

pi - Player item index (requires item.getPlayer() != null), or -1

item - Item for owning player, coordinate on board, and level/strength

Throws:

java.lang.IllegalArgumentException - if typeKey is null, or pi != -1 but item.getPlayer() is null, or gi == -1 and pi == -1

java.lang.NullPointerException - if game or item is null

SOCSetSpecialItem

public SOCSetSpecialItem(java.lang.String ga,
                         int op,
                         java.lang.String typeKey,
                         int gi,
                         int pi,
                         int pn)
                  throws java.lang.IllegalArgumentException,
                         java.lang.NullPointerException

Create a SOCSetSpecialItem message, specifying all field values except coordinate (-1), level (0), stringValue (null).

Parameters:

ga - Name of the game

op - Operation code: see op for values

typeKey - Special item type key; see the SOCSpecialItem class javadoc for details

gi - Game item index, or -1

pi - Player item index (requires pn != -1), or -1

pn - Currently owning player number, or -1

Throws:

java.lang.IllegalArgumentException

java.lang.NullPointerException

SOCSetSpecialItem

public SOCSetSpecialItem(java.lang.String ga,
                         int op,
                         java.lang.String typeKey,
                         int gi,
                         int pi,
                         int pn,
                         int co,
                         int lv,
                         java.lang.String sv)
                  throws java.lang.IllegalArgumentException

Create a SOCSetSpecialItem message, specifying all field values.

Parameters:

ga - Name of the game

op - Operation code: see op for values

typeKey - Special item type key; see the SOCSpecialItem class javadoc for details

gi - Game item index, or -1

pi - Player item index (requires pn != -1), or -1

pn - Currently owning player number, or -1

co - Optional coordinate on board, or -1

lv - Optional built level/strength, or 0

sv - Optional stringValue from SOCSpecialItem.getStringValue(), or null

Throws:

java.lang.IllegalArgumentException - if ga or typeKey is null, or pn != -1 but pi == -1, or gi == -1 and pi == -1, or sv fails SOCMessage.isSingleLineAndSafe(String)

Method Detail

getGame

public java.lang.String getGame()

Description copied from interface: SOCMessageForGame

Name of game this message is for. Must not be null if message is in per-game structures or code.

At the server, the message treater dispatches incoming SOCMessageForGames based on their getGame():

• null: Message is ignored
• SOCMessage.GAME_NONE: Message is handled by SOCServer itself
• Any other game name: Looks for a game with that name, to dispatch to the GameHandler for that game's type. If no game with that name is found, the message is ignored.

Specified by:

getGame in interface SOCMessageForGame

Returns:

the name of the game

See Also:

SOCMessage.GAME_NONE

parseDataStr

public static SOCSetSpecialItem parseDataStr(java.lang.String s)

Parse the command String into a SOCSetSpecialItem message.

Parameters:

s - the String to parse, from toCmd()

Returns:

a SOCSetSpecialItem message, or null if the data is garbled

getMinimumVersion

public int getMinimumVersion()

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

Overrides:

getMinimumVersion in class SOCMessage

Returns:

Version number, 2000 for JSettlers 2.0.00.

toCmd

public java.lang.String toCmd()

SETSPECIALITEM sep game sep2 operation sep2 typeKey sep2 gameItemIndex sep2 playerItemIndex sep2 playerNumber sep2 coord sep2 level sep2 sv

If sv is null, it's sent as EMPTYSTR.

Specified by:

toCmd in class SOCMessage

Returns:

the command string

toString

public java.lang.String toString()

Description copied from class: SOCMessage

Simple human-readable representation, used for debug purposes.

Specified by:

toString in class SOCMessage

Returns:

a human readable form of the message