soc.message
Class SOCMessage

java.lang.Object
  soc.message.SOCMessage

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

Direct Known Subclasses:

SOCAcceptOffer, SOCAdminPing, SOCAdminReset, SOCBankTrade, SOCBCastTextMsg, SOCBoardLayout, SOCBuildRequest, SOCBuyCardRequest, SOCCancelBuildRequest, SOCChangeFace, SOCChannels, SOCChoosePlayer, SOCChoosePlayerRequest, SOCClearOffer, SOCClearTradeMsg, SOCCreateAccount, SOCDeleteChannel, SOCDeleteGame, SOCDevCard, SOCDevCardCount, SOCDiscard, SOCDiscardRequest, SOCDiscoveryPick, SOCEndTurn, SOCFirstPlayer, SOCGameMembers, SOCGames, SOCGameState, SOCGameStats, SOCGameTextMsg, SOCImARobot, SOCJoin, SOCJoinAuth, SOCJoinGame, SOCJoinGameAuth, SOCJoinGameRequest, SOCLargestArmy, SOCLastSettlement, SOCLeave, SOCLeaveAll, SOCLeaveGame, SOCLongestRoad, SOCMakeOffer, SOCMembers, SOCMessageMulti, SOCMessageTemplate0, SOCMessageTemplate1i, SOCMessageTemplate1s, SOCMessageTemplate2i, SOCMessageTemplate2s, SOCMessageTemplate3s, SOCMonopolyPick, SOCMoveRobber, SOCNewChannel, SOCNewGame, SOCPlayDevCardRequest, SOCPlayerElement, SOCPotentialSettlements, SOCPutPiece, SOCRejectConnection, SOCRejectOffer, SOCResourceCount, SOCRobotDismiss, SOCRollDice, SOCRollDicePrompt, SOCRollDiceRequest, SOCServerPing, SOCSetPlayedDevCard, SOCSetSeatLock, SOCSetupDone, SOCSitDown, SOCStartGame, SOCStatusMessage, SOCTextMsg, SOCTurn, SOCUpdateRobotParams, SOCVersion

public abstract class SOCMessage

extends java.lang.Object

implements java.io.Serializable, java.lang.Cloneable

Messages used for game data, events, and chatting on a channel.

No objects, only strings and integers, are to be sent over the network between servers and clients! Your game's code must guarantee that no string sent contains a separator character (sep_char or sep2_char).

Text announcements (SOCGameTextMsg) are often sent along with data messages.

The message data is sent over the network as type ID + data strings built by each SOCMessage subclass's toCmd() method.

On the remote end, it's reconstructed to a new instance of the appropriate SOCMessage subclass, by the subclass' required method static SOCMessageSubclass parseDataStr(String). parseDataStr is called from toMsg(String) in this class.

The client receives messages in SOCPlayerClient.treat(SOCMessage, boolean). The server receives messages in SOCServer.processCommand(String, StringConnection).

To create a new message type:

• Choose a message type name and ID number. Aadd to the end of the list in this class. Add a comment to note the JSettlers version in which it was introduced, and the date.
• Add it to the switch in toMsg(String). Again, note the version.
• Extend the SOCMessage class, including the required parseDataStr method. (SOCDiceResult and SOCSetTurn are good example subclasses.) Template parent-classes can help; the example subclasses extend them. Be sure to override the minimum version reported in getMinimumVersion().
• Add to the switch in either SOCPlayerClient.treat or SOCServer.processCommand. Note the JSettlers version with a comment.

  Note: Most things added to SOCPlayerClient.treat should also be added to SOCDisplaylessPlayerClient.treat(SOCMessage), to SOCRobotClient.treat(SOCMessage), and possibly to SOCRobotBrain.run().

Backwards compatability: Unknown message types are ignored by client and by server. Technically they are returned as null from toMsg(String) if the local copy of SOCMessage doesn't know that message type.

Format: For most messages, at most one sep token per message, which separates the messagetype number from the message data; multiple SEP2 are allowed after SEP. For multi-messages, multiple SEP are allowed; see SOCMessageMulti.

Author:

Robert S Thomas

See Also:

Serialized Form

Field Summary

static int	ACCEPTOFFER
static int	ADMINPING
static int	ADMINRESET
static int	BANKTRADE
static int	BCASTTEXTMSG
static int	BOARDLAYOUT
static int	BUILDREQUEST
static int	BUYCARDREQUEST
static int	CANCELBUILDREQUEST
static int	CHANGEFACE
static int	CHANNELS
static int	CHOOSEPLAYER
static int	CHOOSEPLAYERREQUEST
static int	CLEAROFFER
static int	CLEARTRADEMSG
static int	CREATEACCOUNT
static int	DELETECHANNEL
static int	DELETEGAME
static int	DEVCARD
static int	DEVCARDCOUNT
static int	DICERESULT
static int	DISCARD
static int	DISCARDREQUEST
static int	DISCOVERYPICK
static int	ENDTURN
static int	FIRSTPLAYER
static int	GAMEMEMBERS
static int	GAMES
static int	GAMESTATE
static int	GAMESTATS
static int	GAMETEXTMSG
static int	IMAROBOT
static int	JOIN
static int	JOINAUTH
static int	JOINGAME
static int	JOINGAMEAUTH
static int	JOINGAMEREQUEST
static int	LARGESTARMY
static int	LASTSETTLEMENT
static int	LEAVE
static int	LEAVEALL
static int	LEAVEGAME
static int	LONGESTROAD
static int	MAKEOFFER
static int	MEMBERS
protected int	messageType An ID identifying the type of message
static int	MONOPOLYPICK
static int	MOVEROBBER
static int	NEWCHANNEL
static int	NEWGAME
static int	NULLMESSAGE message type IDs
static int	PLAYDEVCARDREQUEST
static int	PLAYERELEMENT
static int	POTENTIALSETTLEMENTS
static int	PUTPIECE
static int	REJECTCONNECTION
static int	REJECTOFFER
static int	RESETBOARDAUTH
static int	RESETBOARDREJECT
static int	RESETBOARDREQUEST
static int	RESETBOARDVOTE
static int	RESETBOARDVOTEREQUEST
static int	RESOURCECOUNT
static int	ROBOTDISMISS
static int	ROLLDICE
static int	ROLLDICEPROMPT
static int	ROLLDICEREQUEST
static java.lang.String	sep Token seperators.
static char	sep_char main separator token sep, as character
static java.lang.String	sep2 secondary separator token SEP2, as string
static char	sep2_char secondary separator token sep2, as character
static int	SERVERPING
static int	SETPLAYEDDEVCARD
static int	SETSEATLOCK
static int	SETTURN
static int	SETUPDONE
static int	SITDOWN
static int	STARTGAME
static int	STATUSMESSAGE
static int	TEXTMSG
static int	TURN
static int	UPDATEROBOTPARAMS
static int	VERSION

Constructor Summary

SOCMessage()

Method Summary

int	getMaximumVersion() To identify obsolete message types, give the maximum version where this type is used.
int	getMinimumVersion() To identify new message types, give the minimum version where this type is used.
int	getType()
abstract java.lang.String	toCmd() Converts the contents of this message into a String that can be transferred by a client or server.
static SOCMessage	toMsg(java.lang.String s) Convert a string into a SOCMessage.
static java.lang.String[]	toSingleElemArray(java.lang.String s) Utility, place one string into a new single-element array.
abstract java.lang.String	toString() Simple human-readable representation, used for debug purposes.

Methods inherited from class java.lang.Object

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

Field Detail

NULLMESSAGE

public static final int NULLMESSAGE

message type IDs

See Also:

Constant Field Values

NEWCHANNEL

public static final int NEWCHANNEL

See Also:

Constant Field Values

MEMBERS

public static final int MEMBERS

See Also:

Constant Field Values

CHANNELS

public static final int CHANNELS

See Also:

Constant Field Values

JOIN

public static final int JOIN

See Also:

Constant Field Values

TEXTMSG

public static final int TEXTMSG

See Also:

Constant Field Values

LEAVE

public static final int LEAVE

See Also:

Constant Field Values

DELETECHANNEL

public static final int DELETECHANNEL

See Also:

Constant Field Values

LEAVEALL

public static final int LEAVEALL

See Also:

Constant Field Values

PUTPIECE

public static final int PUTPIECE

See Also:

Constant Field Values

GAMETEXTMSG

public static final int GAMETEXTMSG

See Also:

Constant Field Values

LEAVEGAME

public static final int LEAVEGAME

See Also:

Constant Field Values

SITDOWN

public static final int SITDOWN

See Also:

Constant Field Values

JOINGAME

public static final int JOINGAME

See Also:

Constant Field Values

BOARDLAYOUT

public static final int BOARDLAYOUT

See Also:

Constant Field Values

DELETEGAME

public static final int DELETEGAME

See Also:

Constant Field Values

NEWGAME

public static final int NEWGAME

See Also:

Constant Field Values

GAMEMEMBERS

public static final int GAMEMEMBERS

See Also:

Constant Field Values

STARTGAME

public static final int STARTGAME

See Also:

Constant Field Values

GAMES

public static final int GAMES

See Also:

Constant Field Values

JOINAUTH

public static final int JOINAUTH

See Also:

Constant Field Values

JOINGAMEAUTH

public static final int JOINGAMEAUTH

See Also:

Constant Field Values

IMAROBOT

public static final int IMAROBOT

See Also:

Constant Field Values

JOINGAMEREQUEST

public static final int JOINGAMEREQUEST

See Also:

Constant Field Values

PLAYERELEMENT

public static final int PLAYERELEMENT

See Also:

Constant Field Values

GAMESTATE

public static final int GAMESTATE

See Also:

Constant Field Values

TURN

public static final int TURN

See Also:

Constant Field Values

SETUPDONE

public static final int SETUPDONE

See Also:

Constant Field Values

DICERESULT

public static final int DICERESULT

See Also:

Constant Field Values

DISCARDREQUEST

public static final int DISCARDREQUEST

See Also:

Constant Field Values

ROLLDICEREQUEST

public static final int ROLLDICEREQUEST

See Also:

Constant Field Values

ROLLDICE

public static final int ROLLDICE

See Also:

Constant Field Values

ENDTURN

public static final int ENDTURN

See Also:

Constant Field Values

DISCARD

public static final int DISCARD

See Also:

Constant Field Values

MOVEROBBER

public static final int MOVEROBBER

See Also:

Constant Field Values

CHOOSEPLAYER

public static final int CHOOSEPLAYER

See Also:

Constant Field Values

CHOOSEPLAYERREQUEST

public static final int CHOOSEPLAYERREQUEST

See Also:

Constant Field Values

REJECTOFFER

public static final int REJECTOFFER

See Also:

Constant Field Values

CLEAROFFER

public static final int CLEAROFFER

See Also:

Constant Field Values

ACCEPTOFFER

public static final int ACCEPTOFFER

See Also:

Constant Field Values

BANKTRADE

public static final int BANKTRADE

See Also:

Constant Field Values

MAKEOFFER

public static final int MAKEOFFER

See Also:

Constant Field Values

CLEARTRADEMSG

public static final int CLEARTRADEMSG

See Also:

Constant Field Values

BUILDREQUEST

public static final int BUILDREQUEST

See Also:

Constant Field Values

CANCELBUILDREQUEST

public static final int CANCELBUILDREQUEST

See Also:

Constant Field Values

BUYCARDREQUEST

public static final int BUYCARDREQUEST

See Also:

Constant Field Values

DEVCARD

public static final int DEVCARD

See Also:

Constant Field Values

DEVCARDCOUNT

public static final int DEVCARDCOUNT

See Also:

Constant Field Values

SETPLAYEDDEVCARD

public static final int SETPLAYEDDEVCARD

See Also:

Constant Field Values

PLAYDEVCARDREQUEST

public static final int PLAYDEVCARDREQUEST

See Also:

Constant Field Values

DISCOVERYPICK

public static final int DISCOVERYPICK

See Also:

Constant Field Values

MONOPOLYPICK

public static final int MONOPOLYPICK

See Also:

Constant Field Values

FIRSTPLAYER

public static final int FIRSTPLAYER

See Also:

Constant Field Values

SETTURN

public static final int SETTURN

See Also:

Constant Field Values

ROBOTDISMISS

public static final int ROBOTDISMISS

See Also:

Constant Field Values

POTENTIALSETTLEMENTS

public static final int POTENTIALSETTLEMENTS

See Also:

Constant Field Values

CHANGEFACE

public static final int CHANGEFACE

See Also:

Constant Field Values

REJECTCONNECTION

public static final int REJECTCONNECTION

See Also:

Constant Field Values

LASTSETTLEMENT

public static final int LASTSETTLEMENT

See Also:

Constant Field Values

GAMESTATS

public static final int GAMESTATS

See Also:

Constant Field Values

BCASTTEXTMSG

public static final int BCASTTEXTMSG

See Also:

Constant Field Values

RESOURCECOUNT

public static final int RESOURCECOUNT

See Also:

Constant Field Values

ADMINPING

public static final int ADMINPING

See Also:

Constant Field Values

ADMINRESET

public static final int ADMINRESET

See Also:

Constant Field Values

LONGESTROAD

public static final int LONGESTROAD

See Also:

Constant Field Values

LARGESTARMY

public static final int LARGESTARMY

See Also:

Constant Field Values

SETSEATLOCK

public static final int SETSEATLOCK

See Also:

Constant Field Values

STATUSMESSAGE

public static final int STATUSMESSAGE

See Also:

Constant Field Values

CREATEACCOUNT

public static final int CREATEACCOUNT

See Also:

Constant Field Values

UPDATEROBOTPARAMS

public static final int UPDATEROBOTPARAMS

See Also:

Constant Field Values

ROLLDICEPROMPT

public static final int ROLLDICEPROMPT

See Also:

Constant Field Values

RESETBOARDREQUEST

public static final int RESETBOARDREQUEST

See Also:

Constant Field Values

RESETBOARDAUTH

public static final int RESETBOARDAUTH

See Also:

Constant Field Values

RESETBOARDVOTEREQUEST

public static final int RESETBOARDVOTEREQUEST

See Also:

Constant Field Values

RESETBOARDVOTE

public static final int RESETBOARDVOTE

See Also:

Constant Field Values

RESETBOARDREJECT

public static final int RESETBOARDREJECT

See Also:

Constant Field Values

VERSION

public static final int VERSION

See Also:

Constant Field Values

SERVERPING

public static final int SERVERPING

See Also:

Constant Field Values

sep

public static final java.lang.String sep

Token seperators. At most one SEP per message; multiple SEP2 are allowed after SEP. For multi-messages, multiple SEP are allowed; see SOCMessageMulti.

See Also:

Constant Field Values

sep2

public static final java.lang.String sep2

secondary separator token SEP2, as string

See Also:

Constant Field Values

sep_char

public static final char sep_char

main separator token sep, as character

See Also:

Constant Field Values

sep2_char

public static final char sep2_char

secondary separator token sep2, as character

See Also:

Constant Field Values

messageType

protected int messageType

An ID identifying the type of message

Constructor Detail

SOCMessage

public SOCMessage()

Method Detail

getType

public int getType()

Returns:

the message type

getMinimumVersion

public int getMinimumVersion()

To identify new message types, give the minimum version where this type is used. Default of 1000 (version 1.0.00) unless overridden.

Returns:

Version number, as in 1006 for JSettlers 1.0.06.

getMaximumVersion

public int getMaximumVersion()

To identify obsolete message types, give the maximum version where this type is used. Default (for active messages) returns Integer.MAX_VALUE.

Returns:

Version number, as in 1006 for JSettlers 1.0.06, or Integer.MAX_VALUE.

toCmd

public abstract java.lang.String toCmd()

Converts the contents of this message into a String that can be transferred by a client or server. Your class' required method static SOCMessageSubclass parseDataStr(String) must be able to turn this String back into an instance of the message class.

For most message types, at most one sep token is allowed, separating the type ID from the rest of the parameters. For multi-messages (@link SOCMessageMulti}, multiple sep tokens are allowed. Multi-messages are parsed with: static SOCMessageSubclass parseDataStr(String[])

toString

public abstract java.lang.String toString()

Simple human-readable representation, used for debug purposes.

toSingleElemArray

public static java.lang.String[] toSingleElemArray(java.lang.String s)

Utility, place one string into a new single-element array. To assist with SOCMessageMulti parsing.

Parameters:

s - String to place into array, or null

Returns:

New single-element array containing s, or null if s null.

toMsg

public static SOCMessage toMsg(java.lang.String s)

Convert a string into a SOCMessage. The string is in the form of " sep sep ". If the message type id is unknown, this is printed to System.err.

Parameters:

s - String to convert

Returns:

converted String to a SOCMessage, or null if the string is garbled, or is an unknown command id