dip.order
Interface Orderable

All Known Subinterfaces:
GUIOrder
All Known Implementing Classes:
GUIBuild, GUIConvoy, GUIDefineState, GUIDisband, GUIHold, GUIMove, GUIMoveExplicit, GUIRemove, GUIRetreat, GUISupport, GUIWaive, Order

public interface Orderable

All Order objects must implement this interface.

All classes that use Orders must use Orderable objects, rather than Order objects, for compatibility with the OrderFactory system.

Please note that the Order class provides default implementations for some of these methods, and a number of protected internal methods for convenience.


Method Summary
 void determineDependencies(Adjudicator adjudicator)
          This method is called once all orders are known.
 void evaluate(Adjudicator adjudicator)
          Evaluates an Order.
 java.lang.String getBriefName()
          Returns the Brief name of the Order (e.g., "H" for a Hold order)
 java.lang.String getDefaultFormat()
          Get the default OrderFormat String used to custom-format orders.
 java.lang.String getFullName()
          Returns the Full name of the Order (e.g., "Hold" for a Hold order)
 Power getPower()
          Gets the Power ordering the ordered Source unit
 Location getSource()
          Gets the Location of the ordered unit
 Unit.Type getSourceUnitType()
          Gets the Type of the ordered unit
 java.lang.String toBriefString()
          Prints the entire order, in a brief syntax
 java.lang.String toFormattedString(OrderFormatOptions ofo)
          Formats the order using the OrderFormat format string.
 java.lang.String toFullString()
          Prints the entire order, in a verbose syntax
 void validate(TurnState state, ValidationOptions valOpts, RuleOptions ruleOpts)
          Validate the order; state-independent.
 void verify(Adjudicator adjudicator)
          Ensure that the order can be processed, assuming the complete turn state is known (i.e., all unit positions AND all orders for all powers).
 

Method Detail

getSource

public Location getSource()
Gets the Location of the ordered unit


getSourceUnitType

public Unit.Type getSourceUnitType()
Gets the Type of the ordered unit


getPower

public Power getPower()
Gets the Power ordering the ordered Source unit


getFullName

public java.lang.String getFullName()
Returns the Full name of the Order (e.g., "Hold" for a Hold order)


getBriefName

public java.lang.String getBriefName()
Returns the Brief name of the Order (e.g., "H" for a Hold order)


toBriefString

public java.lang.String toBriefString()
Prints the entire order, in a brief syntax


toFullString

public java.lang.String toFullString()
Prints the entire order, in a verbose syntax


getDefaultFormat

public java.lang.String getDefaultFormat()
Get the default OrderFormat String used to custom-format orders.


toFormattedString

public java.lang.String toFormattedString(OrderFormatOptions ofo)
Formats the order using the OrderFormat format string.

Note that this is equivalent to calling OrderFormat.format(ofo, this, getDefaultFormat()) To print with default (not user-specified) options, use OrderFormat.format(OrderFormatOptions.DEFAULT, this, getDefaultFormat())

While this enables better formatting, it is slower than using the toBriefString() and toFullString() methods.


validate

public void validate(TurnState state,
                     ValidationOptions valOpts,
                     RuleOptions ruleOpts)
              throws OrderException
Validate the order; state-independent.

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 or attempt to discern the orders for any other power or other orders for this power.

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.

Parameters:
state - Current turn state
valOpts - Current validation options
Throws:
OrderException

verify

public void verify(Adjudicator adjudicator)
Ensure that the order can be processed, assuming the complete turn state is known (i.e., all unit positions AND all orders for all powers). This is state-dependent.

For example, this is useful for:

  1. Checking if support orders correctly match a move order
  2. Checking if convoy orders correctly match a move order
  3. etc.

This method should have no side effects, and should have same results if called multiple times

By default, this method does nothing.
DO NOT call validate() within this method; there is no need! The Adjudicator must validate() all orders prior to verification.

Remember, an order that fails validation is an illegal order (and usually converts to a Hold) while an order that fails verification is just a failed order (e.g., a power supports another power's unit move, but the other power's unit is ordered to hold), NOT an illegal order.

THIS is called BEFORE dependency information is available for the order. so do not assume that dependent order information is available.

This method should NEVER throw checked exceptions (e.g., an OrderException)


determineDependencies

public void determineDependencies(Adjudicator adjudicator)
This method is called once all orders are known. It determines what, if any, orders this order requires to be evaluated in order for this order to be successfully evaluated

This is typically only used by orders generated in the Movement phase.


evaluate

public void evaluate(Adjudicator adjudicator)
Evaluates an Order.

When an order is evaluated, it must change its OrderState. The OrderState cannot be changed once it is set. If an OrderState is uncertain, then it may be re-evaluated until the OrderState is certain (either Success or Failure).

NOTE: this method assumes that all dependency information is complete.



Copyright 2002-2004 Zachary DelProposto / jDip Development Team. All Rights Reserved.