soc.game
Class SOCForceEndTurnResult

java.lang.Object
  soc.game.SOCForceEndTurnResult

public class SOCForceEndTurnResult
extends java.lang.Object

This class holds the results of a call to SOCGame.forceEndTurn(). Specifically, the resulting action type, and possibly list of discarded or returned resources or dev card/inventory item.

forceEndTurn() may also set the game state to SOCGame.OVER. Check for that; it's not reported as part of this object.

The result object isn't intended to be conveyed over a network to clients; the server should translate it into standard SOCMessages which change game state.

Field Summary

static int	FORCE_ENDTURN_LOST_CHOICE Choice lost; a development card or item may be returned to hand, see getReturnedInvItem().
static int	FORCE_ENDTURN_MAX Highest valid FORCE_ENDTURN_ value for SOCGame.forceEndTurn()
static int	FORCE_ENDTURN_MIN SOCGame.forceEndTurn() return values.
static int	FORCE_ENDTURN_NONE Since state is already SOCGame.PLAY1, already OK to end turn.
static int	FORCE_ENDTURN_RSRC_DISCARD Resources have been randomly discarded, or gained from SOCBoardLarge.GOLD_HEX or a canceled piece placement.
static int	FORCE_ENDTURN_RSRC_DISCARD_WAIT Resources have been randomly discarded, or gained from SOCBoardLarge.GOLD_HEX or a canceled piece placement.
static int	FORCE_ENDTURN_RSRC_RET_UNPLACE Sent both for placement of bought pieces, and for "free" pieces from road-building cards.
static int	FORCE_ENDTURN_SKIP_START_ADV Skip an initial road or settlement; current player has advanced forward, state changes to SOCGame.START1A or SOCGame.START3A.
static int	FORCE_ENDTURN_SKIP_START_ADVBACK Skip an initial road or settlement; current player has advanced backward, state changes to SOCGame.START2A.
static int	FORCE_ENDTURN_SKIP_START_TURN Skip an initial road or settlement; state changes to SOCGame.PLAY1, and SOCGame.endTurn() should be called.
static int	FORCE_ENDTURN_UNPLACE_ROBBER Robber movement has been cancelled.
private SOCResourceSet	gainLoss Resources gained (returned to cancel piece placement) or lost (discarded), or null.
private SOCInventoryItem	invCard Development card type / item returned to player's inventory, or null.
private int	result Result type, like FORCE_ENDTURN_NONE
private boolean	rsrcLoss If true, player's resources are lost (discarded), not gained (returned).
private boolean	updatedFP If true, game's SOCGame.getFirstPlayer() was changed.
private boolean	updatedLP If true, game's lastPlayer was changed.

Constructor Summary

	SOCForceEndTurnResult(int res) Creates a new SOCForceEndTurnResult object, no resources gained/lost.
	SOCForceEndTurnResult(int res, boolean updateFirstPlayer, boolean updateLastPlayer, SOCResourceSet rsrcGained) Creates a new SOCForceEndTurnResult object, from start states, possibly changing the game's firstplayer or lastplayer.
	SOCForceEndTurnResult(int res, SOCInventoryItem item) Creates a new SOCForceEndTurnResult object, optionally with a development card or inventory option regained (returned to the player's hand).
	SOCForceEndTurnResult(int res, SOCResourceSet gained) Creates a new SOCForceEndTurnResult object, with resources gained.
	SOCForceEndTurnResult(int res, SOCResourceSet gainedLost, boolean isLoss) Creates a new SOCForceEndTurnResult object, with resources gained/lost.
private	SOCForceEndTurnResult(int res, SOCResourceSet gainedLost, boolean isLoss, boolean updateFirstPlayer, boolean updateLastPlayer) Creates a new SOCForceEndTurnResult object.

Method Summary

boolean	didUpdateFP() Did the game's SOCGame.getFirstPlayer() change?
boolean	didUpdateLP() Did the game's lastPlayer change? Calling SOCGame.setFirstPlayer(int) will also calculate its lastPlayer based on vacant seats and firstPlayer.
SOCResourceSet	getResourcesGainedLost() Get the resources gained (returned to cancel piece placement, or received from placing at a gold hex) or lost (discarded), if any.
int	getResult() Get the force result type.
SOCInventoryItem	getReturnedInvItem() Is a development card or inventory item being returned to the player's hand?
boolean	isLoss() Is player losing, or gaining, the resources of getResourcesGainedLost()?

Methods inherited from class java.lang.Object

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

Field Detail

result

private int result

Result type, like FORCE_ENDTURN_NONE

gainLoss

private SOCResourceSet gainLoss

Resources gained (returned to cancel piece placement) or lost (discarded), or null. Lost resources are negative values in this set.

rsrcLoss

private boolean rsrcLoss

If true, player's resources are lost (discarded), not gained (returned).

invCard

private SOCInventoryItem invCard

Development card type / item returned to player's inventory, or null. Currently used with FORCE_ENDTURN_LOST_CHOICE and FORCE_ENDTURN_UNPLACE_ROBBER.

updatedFP

private boolean updatedFP

If true, game's SOCGame.getFirstPlayer() was changed.

Since:

1.1.09

updatedLP

private boolean updatedLP

If true, game's lastPlayer was changed. Calling SOCGame.setFirstPlayer(int) will also calculate its lastPlayer based on vacant seats and firstPlayer.

Since:

1.1.09

FORCE_ENDTURN_MIN

public static final int FORCE_ENDTURN_MIN

SOCGame.forceEndTurn() return values. FORCE_ENDTURN_MIN is the lowest valid value.

See Also:

Constant Field Values

FORCE_ENDTURN_NONE

public static final int FORCE_ENDTURN_NONE

Since state is already SOCGame.PLAY1, already OK to end turn. No action was taken by forceEndTurn.

See Also:

Constant Field Values

FORCE_ENDTURN_SKIP_START_ADV

public static final int FORCE_ENDTURN_SKIP_START_ADV

Skip an initial road or settlement; current player has advanced forward, state changes to SOCGame.START1A or SOCGame.START3A. May have changed game's firstPlayer or lastPlayer; check didUpdateFP() and didUpdateLP().

See Also:

Constant Field Values

FORCE_ENDTURN_SKIP_START_ADVBACK

public static final int FORCE_ENDTURN_SKIP_START_ADVBACK

Skip an initial road or settlement; current player has advanced backward, state changes to SOCGame.START2A. May have changed game's firstPlayer or lastPlayer; check didUpdateFP() and didUpdateLP().

See Also:

Constant Field Values

FORCE_ENDTURN_SKIP_START_TURN

public static final int FORCE_ENDTURN_SKIP_START_TURN

Skip an initial road or settlement; state changes to SOCGame.PLAY1, and SOCGame.endTurn() should be called.

See Also:

Constant Field Values

FORCE_ENDTURN_RSRC_RET_UNPLACE

public static final int FORCE_ENDTURN_RSRC_RET_UNPLACE

Sent both for placement of bought pieces, and for "free" pieces from road-building cards. Resources for the bought piece are gained (given back to the player). getResourcesGainedLost() contains the returned resources, or nothing if the piece was free.

See Also:

Constant Field Values

FORCE_ENDTURN_UNPLACE_ROBBER

public static final int FORCE_ENDTURN_UNPLACE_ROBBER

Robber movement has been cancelled. Call getReturnedInvItem() to see if a Knight card was returned.

See Also:

Constant Field Values

FORCE_ENDTURN_RSRC_DISCARD

public static final int FORCE_ENDTURN_RSRC_DISCARD

Resources have been randomly discarded, or gained from SOCBoardLarge.GOLD_HEX or a canceled piece placement. Ready to end turn. rsrcLoss is set or cleared. getResourcesGainedLost() contains the resources.

See Also:

Constant Field Values

FORCE_ENDTURN_RSRC_DISCARD_WAIT

public static final int FORCE_ENDTURN_RSRC_DISCARD_WAIT

Resources have been randomly discarded, or gained from SOCBoardLarge.GOLD_HEX or a canceled piece placement. Cannot end turn yet; other players must discard or gain. SOCGame.isForcingEndTurn() is set. rsrcLoss is set or cleared. getResourcesGainedLost() contains the resources.

See Also:

Constant Field Values

FORCE_ENDTURN_LOST_CHOICE

public static final int FORCE_ENDTURN_LOST_CHOICE

Choice lost; a development card or item may be returned to hand, see getReturnedInvItem().

See Also:

Constant Field Values

FORCE_ENDTURN_MAX

public static final int FORCE_ENDTURN_MAX

Highest valid FORCE_ENDTURN_ value for SOCGame.forceEndTurn()

See Also:

Constant Field Values

Constructor Detail

SOCForceEndTurnResult

public SOCForceEndTurnResult(int res)
                      throws java.lang.IllegalArgumentException

Creates a new SOCForceEndTurnResult object, no resources gained/lost.

Parameters:

res - Result type, from constants in this class (FORCE_ENDTURN_UNPLACE_ROBBER, etc.)

Throws:

java.lang.IllegalArgumentException - If res is not in the range FORCE_ENDTURN_MIN to FORCE_ENDTURN_MAX.

SOCForceEndTurnResult

public SOCForceEndTurnResult(int res,
                             boolean updateFirstPlayer,
                             boolean updateLastPlayer,
                             SOCResourceSet rsrcGained)
                      throws java.lang.IllegalArgumentException

Creates a new SOCForceEndTurnResult object, from start states, possibly changing the game's firstplayer or lastplayer.

Parameters:

res - Result type, from constants in this class (FORCE_ENDTURN_UNPLACE_ROBBER, etc.)

updateFirstPlayer - Was SOCGame.getFirstPlayer() changed?

updateLastPlayer - Was game's lastPlayer changed?

rsrcGained - null, or randomly picked resources from gold hex from state STARTS_WAITING_FOR_PICK_GOLD_RESOURCE

Throws:

java.lang.IllegalArgumentException - If res is not in the range FORCE_ENDTURN_MIN to FORCE_ENDTURN_MAX.

Since:

1.1.09

SOCForceEndTurnResult

public SOCForceEndTurnResult(int res,
                             SOCInventoryItem item)
                      throws java.lang.IllegalArgumentException

Creates a new SOCForceEndTurnResult object, optionally with a development card or inventory option regained (returned to the player's hand). Sets getReturnedInvItem().

Parameters:

res - Result type, from constants in this class (FORCE_ENDTURN_UNPLACE_ROBBER, etc.)

item - Development card or inventory item regained, or null if none

Throws:

java.lang.IllegalArgumentException - If res is not in the range FORCE_ENDTURN_MIN to FORCE_ENDTURN_MAX

SOCForceEndTurnResult

public SOCForceEndTurnResult(int res,
                             SOCResourceSet gained)
                      throws java.lang.IllegalArgumentException

Creates a new SOCForceEndTurnResult object, with resources gained. This can occur when placing a piece is canceled.

Parameters:

res - Result type, from constants in this class (FORCE_ENDTURN_UNPLACE_ROBBER, etc.)

gained - Resources gained (returned to cancel piece placement), or null.

Throws:

java.lang.IllegalArgumentException - If res is not in the range FORCE_ENDTURN_MIN to FORCE_ENDTURN_MAX.

SOCForceEndTurnResult

public SOCForceEndTurnResult(int res,
                             SOCResourceSet gainedLost,
                             boolean isLoss)
                      throws java.lang.IllegalArgumentException

Creates a new SOCForceEndTurnResult object, with resources gained/lost. This can occur from the robber or knight, the gold hex, or when placing a piece is canceled.

Parameters:

res - Result type, from constants in this class (FORCE_ENDTURN_RSRC_DISCARD, etc.)

gainedLost - Resources gained (returned to cancel piece placement) or lost (discarded), or null.

isLoss - Resources are lost (discarded), not gained (returned to player).

Throws:

java.lang.IllegalArgumentException - If res is not in the range FORCE_ENDTURN_MIN to FORCE_ENDTURN_MAX.

SOCForceEndTurnResult

private SOCForceEndTurnResult(int res,
                              SOCResourceSet gainedLost,
                              boolean isLoss,
                              boolean updateFirstPlayer,
                              boolean updateLastPlayer)
                       throws java.lang.IllegalArgumentException

Creates a new SOCForceEndTurnResult object.

Parameters:

res - Result type, from constants in this class (FORCE_ENDTURN_UNPLACE_ROBBER, etc.)

gainedLost - Resources gained (returned to cancel piece placement) or lost (discarded), or null.

isLoss - Resources are lost (discarded), not gained (returned to player).

updateFirstPlayer - Was SOCGame.getFirstPlayer() changed?

updateLastPlayer - Was game's lastPlayer changed?

Throws:

java.lang.IllegalArgumentException - If res is not in the range FORCE_ENDTURN_MIN to FORCE_ENDTURN_MAX.

Method Detail

getResult

public int getResult()

Get the force result type.

Returns:

Result type, from constants in this class (FORCE_ENDTURN_UNPLACE_ROBBER, etc.)

getResourcesGainedLost

public SOCResourceSet getResourcesGainedLost()

Get the resources gained (returned to cancel piece placement, or received from placing at a gold hex) or lost (discarded), if any. Lost resources are signaled by isLoss().

Returns:

gained or lost resources, or null

isLoss

public boolean isLoss()

Is player losing, or gaining, the resources of getResourcesGainedLost()?

Returns:

true if resource loss, false if gain, for the player

didUpdateFP

public boolean didUpdateFP()

Did the game's SOCGame.getFirstPlayer() change?

Since:

1.1.09

didUpdateLP

public boolean didUpdateLP()

Did the game's lastPlayer change? Calling SOCGame.setFirstPlayer(int) will also calculate its lastPlayer based on vacant seats and firstPlayer.

Since:

1.1.09

getReturnedInvItem

public SOCInventoryItem getReturnedInvItem()

Is a development card or inventory item being returned to the player's hand?

Returns:

Development card or item returned, or null