soc.message
Class SOCInventoryItemAction

java.lang.Object
  soc.message.SOCMessage
      soc.message.SOCInventoryItemAction

All Implemented Interfaces:

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

public class SOCInventoryItemAction
extends SOCMessage
implements SOCMessageForGame

This message is a client player request, or server response or announcement, about SOCInventoryItems in a player's inventory.

Inventory items are held by a player like SOCDevCards. These special items are used by certain scenarios, and the meaning of each one's itemType is specific to the scenario. An item's current state can be NEW and not yet playable; PLAYABLE now; or KEPT until end of game.

Possible message traffic, by action:

• From Server to one client or all clients: Add an item to a player's inventory with a certain state: ADD_PLAYABLE, ADD_OTHER
• From Client: Player is requesting to PLAY a playable item
• If the client can't currently play that type, server responds with CANNOT_PLAY, optionally with a reasonCode
• When a player plays an item, server sends PLAYED to all clients, including all flags such as isKept and canCancelPlay. Messages after that will indicate new game state or any other results of playing the item.
• If some other game action or event causes an item to need placement on the board, but it was never in the player's inventory, server sends PLACING_EXTRA to give the item details such as itemType and canCancelPlay. Play/placement rules are specific to each kind of inventory action, and the PLACING_EXTRA message may be sent before a game state change or other messages necessary for placement. See PLACING_EXTRA's javadoc for client handling.

When the server sends a SOCInventoryItemAction, it doesn't also send a SOCGameServerText explaining the details; the client must print such text based on the SOCInventoryItemAction received.

Based on SOCDevCardAction.

Notes for certain special items:

• _SC_FTRI: Trade ports received as gifts.
  In state SOCGame.PLAY1 or SOCGame.SPECIAL_BUILDING, current player sends this when they have a port in their inventory. itemType is the negative of the port type to play.

  If they can place now, server broadcasts SOCInventoryItemAction(PLAYED) to the game to remove it from player's inventory, then sends SOCGameState(PLACING_INV_ITEM). (Player interface shouldn't let them place before the new game state is sent.) When the requesting client receives this PLAYED message, it will call SOCGame.setPlacingItem(SOCInventoryItem) because SOCInventoryItem.isPlayForPlacement(SOCGame, int) is true for _SC_FTRI.

  Otherwise, server responds with CANNOT_PLAY with one of these reasonCodes:
  1 if the requested port type isn't in the player's inventory
  2 if the game options don't permit moving trade ports
  3 if the game state or current player aren't right to request placement now
  4 if player's SOCPlayer.getPortMovePotentialLocations(boolean) is null
  

  The port may be placed immediately if the player puts a ship at its original location and has a coastal settlement with room for a port. Such a port will never be in the player's inventory. The server will immediately send that player PLACING_EXTRA with the port's details; see that action's javadoc for client handling of the message.

  When the player chooses their placement location, they should send SOCSimpleRequest(TRADE_PORT_PLACE). See that constant's javadoc for details.

Since:

2.0.00

See Also:

Serialized Form

Field Summary

int	action Action, such as ADD_PLAYABLE or PLAY
static int	ADD_OTHER item action ADD_OTHER: From server, add as New or Kept to player's inventory, depending on whether this item's type is kept until end of game
static int	ADD_PLAYABLE item action ADD_PLAYABLE: From server, add as Playable to player's inventory
boolean	canCancelPlay If true, this item being added and its later play or placement can be canceled: SOCInventoryItem.canCancelPlay.
static int	CANNOT_PLAY item action CANNOT_PLAY: From server, the player or bot can't play the requested item at this time.
private static int	FLAG_CANCPLAY canCancelPlay flag position for sending over network in a bit field
private static int	FLAG_ISKEPT isKept flag position for sending over network in a bit field
private static int	FLAG_ISVP isVP flag position for sending over network in a bit field
private java.lang.String	game Name of game; getter required by SOCMessageForGame
boolean	isKept If true, this item being added is kept in inventory until end of game.
boolean	isVP If true, this item being added is worth victory points.
int	itemType The item type code, from SOCInventoryItem.itype
static int	PLACING_EXTRA If some other game action or event causes an item to need placement on the board, but it was never in the player's inventory, server sends PLACING_EXTRA to give the item details such as itemType and canCancelPlay.
static int	PLAY item action PLAY: Client request to play a PLAYABLE item
static int	PLAYED item action PLAYED: From server, item was played.
int	playerNumber Player number, or -1 for action CANNOT_PLAY
int	reasonCode Optional reason codes for the CANNOT_PLAY action, corresponding to SOCGame.canPlayInventoryItem(int, int) return codes, or 0.
private static long	serialVersionUID

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

SOCInventoryItemAction(java.lang.String ga, int pn, int ac, int it)
Create an InventoryItemAction message, skipping the boolean flags.

SOCInventoryItemAction(java.lang.String ga, int pn, int ac, int it, boolean kept, boolean vp, boolean canCancel)
Create an InventoryItemAction message, with any possible flags.

SOCInventoryItemAction(java.lang.String ga, int pn, int ac, int it, int rc)
Create an InventoryItemAction message, with optional reasonCode.

Method Summary

java.lang.String	getGame() Name of game this message is for.
static SOCInventoryItemAction	parseDataStr(java.lang.String s) Parse the command String into an InventoryItemAction message.
java.lang.String	toCmd() INVENTORYITEMACTION sep game sep2 playerNumber sep2 action sep2 itemType [ sep2 rcode ]
static java.lang.String	toCmd(java.lang.String ga, int pn, int ac, int it, int rc) INVENTORYITEMACTION sep game sep2 playerNumber sep2 action sep2 itemType [ sep2 rcode ]
java.lang.String	toString() Simple human-readable representation, used for debug purposes.

Methods inherited from class soc.message.SOCMessage

arrayIntoStringBuf, enumIntoStringBuf, getClassNameShort, getMaximumVersion, getMinimumVersion, 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

ADD_PLAYABLE

public static final int ADD_PLAYABLE

item action ADD_PLAYABLE: From server, add as Playable to player's inventory

See Also:

Constant Field Values

ADD_OTHER

public static final int ADD_OTHER

item action ADD_OTHER: From server, add as New or Kept to player's inventory, depending on whether this item's type is kept until end of game

See Also:

Constant Field Values

PLAY

public static final int PLAY

item action PLAY: Client request to play a PLAYABLE item

See Also:

Constant Field Values

CANNOT_PLAY

public static final int CANNOT_PLAY

item action CANNOT_PLAY: From server, the player or bot can't play the requested item at this time. This is sent only to the requesting player, so playerNumber is always -1 in this message.

See Also:

Constant Field Values

PLAYED

public static final int PLAYED

item action PLAYED: From server, item was played. Check the isKept flag to see if the item should be removed from inventory, or remain with state KEPT. Call SOCInventoryItem.isPlayForPlacement(SOCGame, int): If true, playing this item requires placement; client receiving the message should call SOCGame.setPlacingItem(SOCInventoryItem).

See Also:

Constant Field Values

PLACING_EXTRA

public static final int PLACING_EXTRA

If some other game action or event causes an item to need placement on the board, but it was never in the player's inventory, server sends PLACING_EXTRA to give the item details such as itemType and canCancelPlay. May be sent to entire game or just to the placing current player.

Play/placement rules are specific to each kind of inventory action, and the PLACING_EXTRA message may be sent before a game state change or other messages necessary for placement. The client handling PLACING_EXTRA should call SOCGame.setPlacingItem(SOCInventoryItem) and wait for those other messages. When they arrive, client can call SOCGame.getPlacingItem() to retrieve the item details.

See Also:

Constant Field Values

FLAG_ISKEPT

private static final int FLAG_ISKEPT

isKept flag position for sending over network in a bit field

See Also:

Constant Field Values

FLAG_ISVP

private static final int FLAG_ISVP

isVP flag position for sending over network in a bit field

See Also:

Constant Field Values

FLAG_CANCPLAY

private static final int FLAG_CANCPLAY

canCancelPlay flag position for sending over network in a bit field

See Also:

Constant Field Values

game

private final java.lang.String game

Name of game; getter required by SOCMessageForGame

playerNumber

public final int playerNumber

Player number, or -1 for action CANNOT_PLAY

itemType

public final int itemType

The item type code, from SOCInventoryItem.itype

action

public final int action

Action, such as ADD_PLAYABLE or PLAY

reasonCode

public final int reasonCode

Optional reason codes for the CANNOT_PLAY action, corresponding to SOCGame.canPlayInventoryItem(int, int) return codes, or 0. Also used within this class to encode isKept and isVP over the network.

isKept

public final boolean isKept

If true, this item being added is kept in inventory until end of game. This flag is sent for all actions except PLAY and CANNOT_PLAY.

isVP

public final boolean isVP

If true, this item being added is worth victory points. This flag is sent for all actions except PLAY and CANNOT_PLAY.

canCancelPlay

public final boolean canCancelPlay

If true, this item being added and its later play or placement can be canceled: SOCInventoryItem.canCancelPlay. This flag is sent for all actions except PLAY and CANNOT_PLAY.

Constructor Detail

SOCInventoryItemAction

public SOCInventoryItemAction(java.lang.String ga,
                              int pn,
                              int ac,
                              int it)

Create an InventoryItemAction message, skipping the boolean flags.

If the action is to add a card with isKept, isVP, or canCancelPlay, use the SOCInventoryItemAction(String, int, int, int, boolean, boolean, boolean) constructor instead.

If the action is the server replying with CANNOT_PLAY with a reason code, use the SOCInventoryItemAction(String, int, int, int, int) constructor instead.

Parameters:

ga - name of the game

pn - the player number, or -1 for action type CANNOT_PLAY

ac - the type of action, such as PLAY

it - the item type code, from SOCInventoryItem.itype

SOCInventoryItemAction

public SOCInventoryItemAction(java.lang.String ga,
                              int pn,
                              int ac,
                              int it,
                              boolean kept,
                              boolean vp,
                              boolean canCancel)

Create an InventoryItemAction message, with any possible flags. reasonCode will be 0.

Parameters:

ga - name of the game

pn - the player number, or -1 for action type CANNOT_PLAY

ac - the type of action, such as ADD_PLAYABLE or PLAYED

it - the item type code, from SOCInventoryItem.itype

kept - If true, this is an add or play message with the isKept flag set

vp - If true, this is an add or play message with the isVP flag set

canCancel - If true, this is an add or play message with the canCancelPlay flag set

SOCInventoryItemAction

public SOCInventoryItemAction(java.lang.String ga,
                              int pn,
                              int ac,
                              int it,
                              int rc)

Create an InventoryItemAction message, with optional reasonCode. The isKept, isVP, and canCancelPlay flags will be false.

Parameters:

ga - name of the game

pn - the player number, or -1 for action type CANNOT_PLAY

ac - the type of action, such as ADD_PLAYABLE

it - the item type code, from SOCInventoryItem.itype

rc - reason code for reasonCode, or 0

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 game name

See Also:

SOCMessage.GAME_NONE

toCmd

public java.lang.String toCmd()

INVENTORYITEMACTION sep game sep2 playerNumber sep2 action sep2 itemType [ sep2 rcode ]

Specified by:

toCmd in class SOCMessage

Returns:

the command String

toCmd

public static java.lang.String toCmd(java.lang.String ga,
                                     int pn,
                                     int ac,
                                     int it,
                                     int rc)

INVENTORYITEMACTION sep game sep2 playerNumber sep2 action sep2 itemType [ sep2 rcode ]

Parameters:

ga - the game name

pn - the player number

ac - the type of action

it - the item type code

rc - the reason code if action == CANNOT_PLAY

Returns:

the command string

parseDataStr

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

Parse the command String into an InventoryItemAction message.

Parameters:

s - the String to parse

Returns:

an InventoryItemAction message, or null of the data is garbled

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