dip.world
Class Location

java.lang.Object
  extended bydip.world.Location
All Implemented Interfaces:
java.lang.Cloneable

public class Location
extends java.lang.Object
implements java.lang.Cloneable

A Location defines where an object on the map exists.

Locations are immutable. Convenience methods are provided for obtaining adjacency information.


Field Summary
static Location[] EMPTY
          Constant defining an empty array of Location() objects
 
Constructor Summary
Location(Province province, Coast coast)
          Create a Location object
 
Method Summary
 void appendBrief(java.lang.StringBuffer sb)
          Append the brief Location name to the StringBuffer (e.g., spa/sc)
 void appendFull(java.lang.StringBuffer sb)
          Append the full Location name to the StringBuffer.
 java.lang.Object clone()
          Implements a clone.
 boolean equals(java.lang.Object obj)
          Determines if two Locations are equal.
 boolean equalsLoosely(Location loc)
          Determines if two Locations are "loosely" equal.
 Coast getCoast()
          Get the Coast for this Location
 Province getProvince()
          Get the Province for this Location
 Location getValidated(Unit.Type unitType)
           Simple Validate This is typically used for support destinations, e.g.
 Location getValidatedAndDerived(Unit.Type unitType, Unit existingUnit)
           This extends the simple getValidated() method, by performing additional validation/checking given turnstate information.
 Location getValidatedSetup(Unit.Type unitType)
          This is mainly used for game setup (WorldFactory).
 Location getValidatedWithMove(Unit.Type unitType, Location from)
           This extends the simple validate method, be performing additional checking for move orders.
 int hashCode()
          Hashcode for Location.
 boolean isAdjacent(Location location)
          Determines if the two locations are adjacent (connected), taking coasts into account as well.
 boolean isAdjacent(Province destProvince)
          Determines if the two locations are adjacent (connected).
 boolean isConvoyableCoast()
          Convenience method.
 boolean isProvinceEqual(Location location)
          Returns true if the Province in both locations is equal, ignoring the coasts.
 boolean isProvinceEqual(Province province)
          Returns true if the Province in this location is equal to the province argument; coasts are ignored.
 boolean isTouching(Province destProvince)
          Returns true if this location is touching the given province.
 java.lang.String toLongString()
          Returns the full (long) Locatin name (as per appendFull()) as a String
 java.lang.String toString()
          Returns the short Location name (as per appendBrief()) as a String
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY

public static final Location[] EMPTY
Constant defining an empty array of Location() objects

Constructor Detail

Location

public Location(Province province,
                Coast coast)
Create a Location object

Method Detail

getProvince

public final Province getProvince()
Get the Province for this Location


getCoast

public final Coast getCoast()
Get the Coast for this Location


isConvoyableCoast

public boolean isConvoyableCoast()
Convenience method. Determines if the Location has a convoyable coastal Province.


isTouching

public boolean isTouching(Province destProvince)
Returns true if this location is touching the given province. Note that "Touching" does not nescessarily imply connectedness (adjacency).


isAdjacent

public boolean isAdjacent(Province destProvince)
Determines if the two locations are adjacent (connected).

This uses the Province/Coast information of this object, but only uses the Province information supplied; thus it does not check the 'destination' coast.


isAdjacent

public boolean isAdjacent(Location location)
Determines if the two locations are adjacent (connected), taking coasts into account as well.


isProvinceEqual

public boolean isProvinceEqual(Location location)
Returns true if the Province in both locations is equal, ignoring the coasts.


isProvinceEqual

public boolean isProvinceEqual(Province province)
Returns true if the Province in this location is equal to the province argument; coasts are ignored.


clone

public java.lang.Object clone()
Implements a clone. Note that this is not a strict implementation, in that a constructor is invoked for performance reasons, rather than using super.clone().


equals

public boolean equals(java.lang.Object obj)
Determines if two Locations are equal.


hashCode

public int hashCode()
Hashcode for Location.


equalsLoosely

public boolean equalsLoosely(Location loc)
Determines if two Locations are "loosely" equal. This means that the Province must match, but, an Undefined coast will match any coast (including another undefined coast). If coasts are defined, they must match to return true.


toString

public java.lang.String toString()
Returns the short Location name (as per appendBrief()) as a String


toLongString

public java.lang.String toLongString()
Returns the full (long) Locatin name (as per appendFull()) as a String


appendBrief

public void appendBrief(java.lang.StringBuffer sb)
Append the brief Location name to the StringBuffer (e.g., spa/sc)


appendFull

public void appendFull(java.lang.StringBuffer sb)
Append the full Location name to the StringBuffer. (e.g., Spain/South Coast)


getValidatedWithMove

public Location getValidatedWithMove(Unit.Type unitType,
                                     Location from)
                              throws OrderException
        This extends the simple validate method, be performing additional
        checking for move orders. 

        For example:
            F gas-spain

        Now, using the simple validate() method, the above order would fail, becuase
        spain/nc must be specified. However, a fleet in gascony can ONLY move to 
        spain/nc; thus the specification should be optional. If the fleet could move 
        to EITHER coast, then this method offers no gain, and an error will occur.

        Essentially, this 'loosens up' the validate method to account for orders that
        are legal and yet not ambiguous. 

        However, we need to know the 'from' location. 

        This only applies to fleets that are moving into multicoastal provinces.

        some examples:
            F gas-spa       ** illegal; no coast specified
            F gas-spa/nc    ** ok
            F gas-spa/sc    ** illegal; non-adjacent
            F mar-spa/sc    ** ok
            A gas-spa       ** ok (army)
            A gas-spa/nc    ** ok (coast ignored for armies)
            A gas-spa/sc    ** ok (coast ignored for armies)




        This should only be used in Move orders; it should not be used in Convoy orders,
        since only Armies can be convied, nor should it be used for Support orders, since
        the destination province may legally be a loose or 'unreachable coast' match.

        NOTE: 'from' MUST BE adjacent to this location for this to work, with a defined
              coast. Thus the 'from' location should be fully validated before this method is used.

        NOTE: This method may return a new Location object, if changes were made,
              or the same Location object, if no changes were made.
        

Throws:
OrderException

getValidatedAndDerived

public Location getValidatedAndDerived(Unit.Type unitType,
                                       Unit existingUnit)
                                throws OrderException
	
        This extends the simple getValidated() method, by performing
        additional validation/checking given turnstate information.

        It is most appropriate for unit source orders. Given the following
        order:
            F xxx SUPPORTS yyy-zzz
        It would be most appropriate to validate the location "xxx" with this 
        method. This is because a unit exists in "xxx", and we can derive/match
        any existing information (coast type, in particular) from the unit.

        It would also be appropriate to validate location yyy with this, because
        we know that a unit must exist in yyy (otherwise the order is invalid).

        Thus coast ambiguities are removed.

        This should NOT be used for validation of destination locations. This is because
        no unit may be in the destination location, and even if there is it wouldn't make
        sense; for example:
            F gas-spain/nc
            A spain
        If we used getValidAndDerived() for "spain/nc", we would derive the coast from the
        army in spain, which would be illegal. Thus a simple validate or a move validate
        should be used instead.


        So: The method works as follows:
            1) calls validate()     "simple validate"
            2) if unit type is a fleet: (if army, we're done)
                a) if coast undefined, derive coast from unit
                b) if coast is defined, ensure that it matches the
                    coast of the unit.

        Fixed: we must give the unit (or null, which may cause a failure).
                The reason to give the unit is that a dislodged unit or
                non-dislodged unit may be req'd depending on what we are
                validating (e.g., retreat orders derive against dislodged
                units)

        A Coast will never be undefined after this method completes.

        NOTE: This method may return a new Location object, if changes were made,
              or the same Location object, if no changes were made.
        

Throws:
OrderException

getValidatedSetup

public Location getValidatedSetup(Unit.Type unitType)
                           throws OrderException
This is mainly used for game setup (WorldFactory). Extends validate() by ensuring that fleets cannot have undefined coasts.

For example: France: F spain is unacceptable; it should be F spain/nc or F spain/sc.

Throws:
OrderException

getValidated

public Location getValidated(Unit.Type unitType)
                      throws OrderException
        Simple Validate

        This is typically used for support destinations, e.g.
            F xxx SUPPORTS A yyy-zzz
        The support destination is "zzz".   

        Does the following:
            For Armies
            ==========
                1) army must not be in a sea space
                2) coast MUST be Coast.NONE (Coast.LAND)
                        if coast is NOT coast.land, it is assumed to be coast.land, because
                        armies are NEVER located in coasts.

            For Fleets
            ==========
                1) must not be in a landlocked space (non-sea, non-coastal)
                2) Any coast that is not illegal is acceptable. In other words:
                    a) if no coast, or single coast, coast changed to Coast.SINGLE
                    b) if multiple coasts exist:
                        1) if no coast specified, coast == Coast.UNDEFINED
                        2) if a coast is specified, it must be one of the recognized
                            legal coats. Thus for spain: 
                                spain, spain/nc, and spain/sc are all legal
                                (resulting in Coast.UNDEFINED, Coast.NORTH, Coast.SOUTH)
                            however,
                                any other coast (spain/ec, spain/wc) are NOT legal, and
                                will cause an exception.
            For Wings
            =========
                1) Always in Coast.WING

        NOTE:   coast may be equal to Coast.UNDEFINED (Coast.ANY) with succesful validation.
                This is intentional! This allows less specific location to match a more specific
                location (e.g., SUPPORT xxx-yyy, and a MOVE zzz-yyy/nc; unspecific "yyy" will 
                still match the more specific "yyy/nc")

        FURTHER NOTE: This method may return a new Location object, if changes were made,
                      or the same Location object, if no changes were made.

        

Throws:
OrderException


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