dip.order
Class Move

java.lang.Object
  dip.order.Order
      dip.order.Move

All Implemented Interfaces:

Orderable, java.io.Serializable

Direct Known Subclasses:

GUIMove, GUIMoveExplicit, Retreat

public class Move

extends Order

Implementation of the Move order.

This has been updated to support the 2003-Dec-16 DATC, specifically, section 4.A.3.

See Also:

Serialized Form

Field Summary

protected boolean	_fmtIsAdjWithConvoy
protected boolean	_hasLandRoute
protected boolean	_isAdjWithPossibleConvoy
protected boolean	_isConvoyIntent
protected boolean	_isViaConvoy
protected java.util.ArrayList	convoyRoutes
protected Location	dest

Fields inherited from class dip.order.Order

ORD_VAL_BORDER, power, src, srcUnitType

Constructor Summary

protected	Move() Creates a Move order
protected	Move(Power power, Location src, Unit.Type srcUnitType, Location dest) Creates a Move order
protected	Move(Power power, Location src, Unit.Type srcUnitType, Location dest, boolean isConvoying) Creates a Move order, with optional convoy preference.
protected	Move(Power power, Location src, Unit.Type srcUnitType, Location dest, java.util.List routes) Creates a Move order with multiple explicit convoy routes.
protected	Move(Power power, Location src, Unit.Type srcUnitType, Location dest, Province[] convoyRoute) Creates a Move order with an explicit convoy route.

Method Summary

void	determineDependencies(Adjudicator adjudicator) Dependencies for a Move order: NOT ADDED: convoy route, if it is a convoyed move note that while a move would depend upon a convoy route, individual convoy orders are not helpful because there may be multiple paths to a destination.
boolean	equals(java.lang.Object obj) Determines if the orders are equal.
void	evaluate(Adjudicator adjudicator) NOTE: this description may be slightly out of date evaluation of Move orders.
protected java.lang.String	formatConvoyRoute(Province[] route, boolean isBrief, boolean useHyphen) Format a convoy route into a String
protected void	formatConvoyRoute(java.lang.StringBuffer sb, Province[] route, boolean isBrief, boolean useHyphen) Format a convoy route into a StringBuffer
java.lang.String	getBriefName() Returns the Brief name of the Order (e.g., "H" for a Hold order)
Province[]	getConvoyRoute() Returns, if set, an explicit convoy route (or the first explicit route if there are multiple routes).
java.util.List	getConvoyRoutes() Returns, if set, all explicit convoy routes as an unmodifiable List.
java.lang.String	getDefaultFormat() Get the default OrderFormat String used to custom-format orders.
Location	getDest() Returns the destination Location of this Move
java.lang.String	getFullName() Returns the Full name of the Order (e.g., "Hold" for a Hold order)
boolean	isAdjWithPossibleConvoy() Returns true if an Army can possibly Move to its destination with a convoy, even though it is adjacent to its destination.
boolean	isConvoying() This is implemented for compatibility; it is no different than isConvoyIntent().
boolean	isConvoyIntent() Returns true if the Intent of this Move order is to Convoy.
boolean	isViaConvoy() Returns true if this Move was explicitly ordered to be by convoy, either by specifying "by convoy" or "via convoy" after the move order, or, by giving an explicit convoy path.
java.lang.String	toBriefString() Prints the entire order, in a brief syntax
java.lang.String	toFullString() Prints the entire order, in a verbose syntax
void	validate(TurnState state, ValidationOptions valOpts, RuleOptions ruleOpts) Validate the order.
protected void	validateTheoreticalConvoyRoute(Position position) Determines if this move has a theoretical explicit or implicit convoy route.
void	verify(Adjudicator adjudicator) Verify this move given completely-known game state.

Methods inherited from class dip.order.Order

addSupportsOfAndMovesToSource, appendBrief, appendFull, checkPower, checkSeasonAdjustment, checkSeasonMovement, checkSeasonRetreat, getPower, getSource, getSourceUnitType, getValidatedUnitType, toFormattedString, toString, validate

Methods inherited from class java.lang.Object

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

Field Detail

dest

protected Location dest

convoyRoutes

protected java.util.ArrayList convoyRoutes

_isViaConvoy

protected boolean _isViaConvoy

_isConvoyIntent

protected boolean _isConvoyIntent

_isAdjWithPossibleConvoy

protected boolean _isAdjWithPossibleConvoy

_fmtIsAdjWithConvoy

protected boolean _fmtIsAdjWithConvoy

_hasLandRoute

protected boolean _hasLandRoute

Constructor Detail

Move

protected Move()

Creates a Move order

Move

protected Move(Power power,
               Location src,
               Unit.Type srcUnitType,
               Location dest)

Creates a Move order

Move

protected Move(Power power,
               Location src,
               Unit.Type srcUnitType,
               Location dest,
               boolean isConvoying)

Creates a Move order, with optional convoy preference.

Move

protected Move(Power power,
               Location src,
               Unit.Type srcUnitType,
               Location dest,
               Province[] convoyRoute)

Creates a Move order with an explicit convoy route. The convoyRoute array must have a length of 3 or more, and not be null.

Move

protected Move(Power power,
               Location src,
               Unit.Type srcUnitType,
               Location dest,
               java.util.List routes)

Creates a Move order with multiple explicit convoy routes. Each entry in routes must be a single-dimensional Province array.

Method Detail

getDest

public Location getDest()

Returns the destination Location of this Move

isViaConvoy

public boolean isViaConvoy()

Returns true if this Move was explicitly ordered to be by convoy, either by specifying "by convoy" or "via convoy" after the move order, or, by giving an explicit convoy path.

Note that this is not always true for all convoyed moves; to check if a move is convoyed, see isConvoying().

Note that explicitly ordering a convoy doesn't really matter unless there are both a land route and a convoy route. See Dec-16-2003 DATC 6.G.8.

isAdjWithPossibleConvoy

public boolean isAdjWithPossibleConvoy()

Returns true if an Army can possibly Move to its destination with a convoy, even though it is adjacent to its destination. This is only really important when a Move to an adjacent province could occur by land or by convoy.

Important Note: This value will not be properly determined until validate() has been called.

isConvoyIntent

public boolean isConvoyIntent()

Returns true if the Intent of this Move order is to Convoy. This is true when:

• isViaConvoy() is false, Source and Dest are not adjacent, both coastal, and there is a theoretical convoy path between them. Note: this can only be determined after validate() has been called.
• hasDualRoute() is true, isViaConvoy() is false, and there is a matching convoy path between source and dest with at least one Convoying Fleet of the same Power as this Move (thus signalling "intent to Convoy"). Note: this can only be determined after verify() has been called.
• isViaConvoy is true, and hasDualRoute() are true. This also can only be determined after verify() has been called.

Note: if this method (or isConvoying()) is to be used during the verify() stage by other orders, they absolutely must check that the Move has already been verified, since move verification can change the value of this method.

isConvoying

public boolean isConvoying()

This is implemented for compatibility; it is no different than isConvoyIntent().

getConvoyRoute

public Province[] getConvoyRoute()

Returns, if set, an explicit convoy route (or the first explicit route if there are multiple routes). Returns null if not convoying or no explicit route was defined.

getConvoyRoutes

public java.util.List getConvoyRoutes()

Returns, if set, all explicit convoy routes as an unmodifiable List. Returns null if not convoying or no explicit route(s) were defined.

getFullName

public java.lang.String getFullName()

Description copied from interface: Orderable

Returns the Full name of the Order (e.g., "Hold" for a Hold order)

getBriefName

public java.lang.String getBriefName()

Description copied from interface: Orderable

Returns the Brief name of the Order (e.g., "H" for a Hold order)

getDefaultFormat

public java.lang.String getDefaultFormat()

Description copied from interface: Orderable

Get the default OrderFormat String used to custom-format orders.

toBriefString

public java.lang.String toBriefString()

Description copied from interface: Orderable

Prints the entire order, in a brief syntax

toFullString

public java.lang.String toFullString()

Description copied from interface: Orderable

Prints the entire order, in a verbose syntax

equals

public boolean equals(java.lang.Object obj)

Description copied from class: Order

Determines if the orders are equal.

Note that full equality MUST be implemented for each subclassed Order object! Subclasses are advised to call the super method for assistance.

Overrides:

equals in class Order

validate

public void validate(TurnState state,
                     ValidationOptions valOpts,
                     RuleOptions ruleOpts)
              throws OrderException

Description copied from class: Order

Validate the order.

This checks the order for legality. An order is not considered to be well-formed until it has been validated. It validates locations (at the least), and other order syntax as appropriate, throwing exceptions if there is a conflict.

This is used by the UI to flag bad orders, as well as by the adjudicator to eliminate bad orders before processing.

Important Note:

The only state that should be assumed is the following: 1) orders for this power (if entered) 2) the positions of all units. Thus, the orders of units not controlled by this power may not be known (in multiplayer games, this information would not be available until adjudication took place). DO NOT assume order information for the units of any power other than that of this unit/order!

Usage Notes:

Subclasses should generally call super.validate() before performing additional validation.

There should be no side effects of calling validate() multiple times, nor should behavior differ between multiple calls of validate(), given the same order.

Specified by:

validate in interface Orderable

Overrides:

validate in class Order

Parameters:

state - Current turn state

valOpts - Current validation options

Throws:

OrderException

validateTheoreticalConvoyRoute

protected void validateTheoreticalConvoyRoute(Position position)
                                       throws OrderException

Determines if this move has a theoretical explicit or implicit convoy route. Throws an exception if

This will only throw an OrderException if there is an Explicit convoy path that is bad (doesn't contain src and dest in route, or doesn't form a route from src->dest), or if there is no implicit theoretical route from src->dest.

An implicit route is assumed if no explicit route has been set.

Throws:

OrderException

formatConvoyRoute

protected java.lang.String formatConvoyRoute(Province[] route,
                                             boolean isBrief,
                                             boolean useHyphen)

Format a convoy route into a String

formatConvoyRoute

protected void formatConvoyRoute(java.lang.StringBuffer sb,
                                 Province[] route,
                                 boolean isBrief,
                                 boolean useHyphen)

Format a convoy route into a StringBuffer

verify

public void verify(Adjudicator adjudicator)

Verify this move given completely-known game state.

Verification must always be performed after strict order validation.

Verify does the following for Move orders:

• Moves involving Fleets or Wings always verify successfully.
• Moves involving armies without theoretical convoy routes always verify successfully.
• Moves with theoretical convoy routes are evaluated as such:
• Moves with explicit convoy routes or "convoy-preferred" moves (isViaConvoy() is true) are evaluated to make sure there is a Legal convoy route. If there is no convoy route, but a land route is available, the land route is used (DATC case 6.G.8)
• Adjacent moves that have a possible ("theoretical") convoy route (therefore, isAdjWithPossibleConvoy() is true) are evaluated to determine intent (2000 rules/DATC 4.A.3); an army will move by land unless there is "intent to convoy". Intent to Convoy is true iff there is both a Legal convoy route and one of the Fleets in that route is of the same Power as the Move order we are evaluating.

Legal convoy routes are defined as a possible (or "theoretical") convoy route (i.e., an unbroken chain of adjacent fleets briding the source and destination), that also have Convoy orders that match this Move.

determineDependencies

public void determineDependencies(Adjudicator adjudicator)

Dependencies for a Move order:

1. NOT ADDED:
   1. convoy route, if it is a convoyed move
      note that while a move would depend upon a convoy route, individual convoy orders are not helpful because there may be multiple paths to a destination. A Path object and path iterator is used to determine convoy-dependency, as required.
   2. Moves to this space
      we are not concerned with moves to this space, unless it is a head-to-head move, which is taken care of below, by setting OrderState appropriately. Move is a special case. Since calculating the 'moves' is the difficult part, when a move is evaluated, the move looks at it's destination space.
2. ADDED:
   1. Supports of this move
   2. Moves to destination space

If destination is a move order, then that move order must be evaluated for an order to succeed. (taken care of by evaluate)

We also determine if this is a head-to-head move order; if so, the head-to-head flag of OrderState is set. A Head-To-Head move is defined as:

	 	A->B and B->A, where neither B nor A is convoyed.
	

Note that head-to-head determination may not be complete until verification is complete, as it depends upon whether this and/or an opposing move is convoyed.

evaluate

public void evaluate(Adjudicator adjudicator)

NOTE: this description may be slightly out of date

                evaluation of Move orders. The algorithm is as follows:
                ======================================================
                1) calculate support of this move (certain & uncertain)

                2) if this is a convoyed move, evaluate convoy route
                        a) if convoy route fails, move fails
                        b) if convoy route uncertain, cannot evaluate move yet
                        c) if convoy route ok, move can be evaluated.

                3) determine order of unit in destination space
                        a) no unit, or unit with Support/Convoy/Hold order
                                1) calculate strengths of all other moves to destination (if present)
                                        this is calculated by the evaluate() method for each Move order, so
                                        several iterations may be required before strengths are in the 'useful'
                                        area.
                                2) calculate defending unit strength (if present; if not, defense_max == 0)
                                        this is calculated by the evaluate() method for the respective order, similar
                                        to 3.a.1
                                3) compare attack_certain (of this move) to attack_max of all other attacks,
                                        and defense_max of destination.
                                        a) if another Move order to destination succeeded, then FAILURE
                                        b) if attack_certain > *all* of the defenders' (attack_max && defense_max)
                                                SUCCESS, unless defender is of the same power, in which case FAILURE 
                                                if SUCCESS, defender (if present) is dislodged
                                        c) if attack_max <= *any* of the defenders' attack_certain or defense_certain
                                                FAILURE (since there would be no way to overcome this difference, 
                                                         regardless of support!) 
                                                         this is a "BOUNCE" [note: this is a key point]
                                        d) otherwise, we remain UNCERTAIN
                        b) self support
                                in cases with self support, the following changes to 3.a are noted below:
                                        1) self support is used to determine strength against other moves (standoffs)
                                                to the destination province. 
                                        2) self support is NOT used to determine strength against *this* move to the
                                                destination province. Self-support can never be used to dislodge a unit,
                                                however, if a unit has enough strength to dislodge, self-support does not
                                                prohibit dislodgement.	

                                                MODIFICATION (6/2/02): Self support *may* be used to determine the strength
                                                of this move to the destination province; if the unit in the destination province
                                                has succesfully moved out, we must compare against all other moves to dest (as in 1) but the
                                                self support can cause us to prevail against other moves to dest as well. Self-support
                                                cannot be used in the dislodge calculation, nor can it prohibit dislodgement.


                        b) unit with Move order, NOT head-to-head (see below for definition)
                                evaluate as 3.a.1-3 however:
                                1)	if we are stronger: (guaranteed success, unless self)
                                                a) if destination move FAILURE, unit is dislodged, unless self; if self, we fail
                                                b) if destination move SUCCESS, unit is not dislodged, we succeed (if self or not)
                                                c) if destination move UNCERTAIN, unit is "maybe" dislodged, unless self;
                                                        if self, we remain uncertain
                                2)	if we are not stronger  (equal-strength)
                                                a) we fail, ONLY if we are 'definately' not stronger (atk.max < def.certain)
                                                b) if destination move SUCCESS, we succeed
                                                c) if destination move UNCERTAIN, we remain uncertain.
                        c) unit is a head-to-head MOVE order
                                definition: 	destination unit is moving to this space, and NEITHER unit is convoyed
                                                                (note: this is set when dependencies are determined)

                                1) evaluate as 3.a.1-3, with the following caveats applied to this vs. head-to-head move:
                                        - we use atk_certain/atk_max of 'head-to-head' unit
                                        a) same as 3.a.3.a
                                        b) same as 3.a.3.b [opposing unit dislodged; NOT a 'maybe' dislodged]
                                                BUT, opposing unit move is marked FAILURE
                                        c) same as 3.a.3.c
                                        d) same as 3.a.3.d	

                        d) comparing against head to head:
                                if comparing against a head-to-head battle, where a unit may be dislodged, remain
                                uncertain until we know if the unit is dislodged; if unit dislodged by head-to-head
                                player, it cannot affect other battles
                                        A->B
                                        B->A
                                        D->B	(and dislodges B)	: no change
                                        HOWEVER, 
                                        A->B, B->A, C->A, and A dislodges B (head to head), C can move to A. 
                                        B does not standoff C because it was dislodged by A in a head-to-head battle.

                                        This is seen in DATC cases 5.A and 7.H (if no "by convoy" is used).
                                                1) isHeadToHead() && EvalState == UNCERTAIN *or* head-to-head part unevaluated:
                                                        UNCERTAIN result.
                                                2) isHeadToHead() && EvalState == FAILURE:
                                                                if disloger == head-to-head, then ignore (do nothing)
                                                3) otherwise, process normally.




                IMPORTANT: 	A move that is 'dislodged' or 'fails' may still offset other moves, and 
                                        still cut support.

                ALSO IMPORTANT: we create dislodged results, instead of failed results, for moves
                                        that are definately dislodged. The adjudicator will create, later, 
                                        dislodged results for 'maybe' dislodged orders.