dip.world
Class Path

java.lang.Object
  extended bydip.world.Path

public class Path
extends java.lang.Object

Determines Convoy paths between points on a Map, and also minimum distances between two map points.

This class is undergoing a transition, and most of the current method will probably be replaced by the static methods based on findAllSeaPaths().


Nested Class Summary
protected  class Path.AnyConvoyPathEvaluator
           
static class Path.ConvoyFAPEvaluator
          FAPEvaluator that checks to see if there is a Fleet present in the given Province that has orders to Convoy, and that convoy order has the given convoy-source and convoy-destination provinces.
static class Path.FAPEvaluator
          FAPEvaluator class.
static class Path.FleetFAPEvaluator
          FAPEvaluator that checks to see if there is a Fleet present in the given Province.
protected static interface Path.PathEvaluator
           
 
Constructor Summary
Path(Adjudicator adjudicator)
          Create a new Path object.
Path(Position position)
          Create a new Path object
 
Method Summary
static Tristate evaluateRoutes(Adjudicator adj, java.util.List routes, Location invalid)
          Determines the adjudication status of static convoy route(s), that are both valid and legal (verified).
static Province[][] findAllSeaPaths(Path.FAPEvaluator evaluator, Province src, Province dest)
          Finds all sea paths from src to dest..
protected  boolean findPathBreadthFirst(Location src, Location dest, Location current, java.util.List path, Path.PathEvaluator pathEvaluator)
          Generalized recursive Path-Finder, Breadth-First search.
 java.util.List getConvoyRoute(Location src, Location dest)
          Returns a path (the first valid path) of a theoretical convoy route between src and dest.
 Tristate getConvoyRouteEvaluation(Location src, Location dest, java.util.List validPath)
          Convenience version of getConvoyRouteEvaluation() where the 'invalid' Location is set to null.
 Tristate getConvoyRouteEvaluation(Location src, Location dest, Location invalid, java.util.List validPath)
          The convoying fleet specified in 'invalid' is considered to fail.
 Tristate getConvoyRouteEvaluation(Move move, Location invalidLoc, java.util.List actualPath)
          Convenience Method.
 java.util.List getLegalConvoyRoute(Location src, Location dest)
          Returns the true convoy route between src & dest; all fleets must have: a Convoy order, with convoy src/dest matching the src/dest given the evaluation state of the Convoy order must not be Tristate.FAILURE
 int getMinDistance(Province src, Province dest)
          Find shortest distance between src & dest.
 boolean isLegalConvoyRoute(Location src, Location dest)
          Find if a true convoy route exists between src & dest; all fleets must have: a Convoy order, with convoy src/dest matching the src/dest given the evaluation state of the Convoy order must not be Tristate.FAILURE
 boolean isPossibleConvoyRoute(Location src, Location dest)
          Returns if there is a "theoretical" convoy route between src and dest.
static boolean isRouteLegal(Adjudicator adj, Province[] route)
          Verifies a route during adjudication stage; Given a valid route, all fleets must have: a Convoy order, with convoy src/dest matching the src/dest given the evaluation state of the Convoy order must not be Tristate.FAILURE
static boolean isRouteValid(Position pos, Location src, Location dest, Province[] route)
          Checks a convoy route to see if it is 'theoretically' valid; this is true iff: route is non-null and length of 3 or more first and last route provinces match src and dest Location provinces first and last provinces are land all other provinces are convoyable (sea or convoyable coast) all convoyable locations have a fleet present route is composed of adjacent spaces
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Path

public Path(Position position)
Create a new Path object


Path

public Path(Adjudicator adjudicator)
Create a new Path object.

Note: this constructor is required for SuperConvoyPathEvaluator / LegalConvoyPathEvaluator which are used by ANY non-theoretical convoy route evaluator.

Method Detail

getConvoyRouteEvaluation

public Tristate getConvoyRouteEvaluation(Move move,
                                         Location invalidLoc,
                                         java.util.List actualPath)
Convenience Method.

This is analagous to other getConvoyRouteEvaluation() methods, however, it will work for both Implicit (jDip finds a path) and Explicit (paths were specified in the Move order, judge-style) paths in a Move order.

This decides whether to use implicit or explicit paths based on if Move.getConvoyRoutes() returns null or not.

The actual path taken will be returned in the actualPath argument.

Note that the invalidLoc (2000 rule support) and actualPath arguments may be null

.

Returns:


isRouteValid

public static boolean isRouteValid(Position pos,
                                   Location src,
                                   Location dest,
                                   Province[] route)
Checks a convoy route to see if it is 'theoretically' valid; this is true iff:
  1. route is non-null and length of 3 or more
  2. first and last route provinces match src and dest Location provinces
  3. first and last provinces are land
  4. all other provinces are convoyable (sea or convoyable coast)
  5. all convoyable locations have a fleet present
  6. route is composed of adjacent spaces


isRouteLegal

public static boolean isRouteLegal(Adjudicator adj,
                                   Province[] route)
Verifies a route during adjudication stage; Given a valid route, all fleets must have:
  1. a Convoy order, with convoy src/dest matching the src/dest given
  2. the evaluation state of the Convoy order must not be Tristate.FAILURE


evaluateRoutes

public static Tristate evaluateRoutes(Adjudicator adj,
                                      java.util.List routes,
                                      Location invalid)
Determines the adjudication status of static convoy route(s), that are both valid and legal (verified). Analagous to getConvoyRouteEvaluation()

See getConvoyRouteEvaluation() for return values.


isPossibleConvoyRoute

public boolean isPossibleConvoyRoute(Location src,
                                     Location dest)
Returns if there is a "theoretical" convoy route between src and dest.

A theoretical convoy route is a string of adjacent fleets that could convoy the desired army from src to dest, but may not have convoy orders to do so.


getConvoyRoute

public java.util.List getConvoyRoute(Location src,
                                     Location dest)
Returns a path (the first valid path) of a theoretical convoy route between src and dest.

A theoretical convoy route is a string of adjacent fleets that could convoy the desired army from src to dest, but may not have convoy orders to do so.


isLegalConvoyRoute

public boolean isLegalConvoyRoute(Location src,
                                  Location dest)
Find if a true convoy route exists between src & dest; all fleets must have:
  1. a Convoy order, with convoy src/dest matching the src/dest given
  2. the evaluation state of the Convoy order must not be Tristate.FAILURE


getLegalConvoyRoute

public java.util.List getLegalConvoyRoute(Location src,
                                          Location dest)
Returns the true convoy route between src & dest; all fleets must have:
  1. a Convoy order, with convoy src/dest matching the src/dest given
  2. the evaluation state of the Convoy order must not be Tristate.FAILURE


getConvoyRouteEvaluation

public Tristate getConvoyRouteEvaluation(Location src,
                                         Location dest,
                                         java.util.List validPath)
Convenience version of getConvoyRouteEvaluation() where the 'invalid' Location is set to null.


getConvoyRouteEvaluation

public Tristate getConvoyRouteEvaluation(Location src,
                                         Location dest,
                                         Location invalid,
                                         java.util.List validPath)
The convoying fleet specified in 'invalid' is considered to fail. (this is for implementing the 2000 rule / multi-route-convoys)

Thus, Say we have the following:
path: a-b-c
if a, b, OR c is marked as 'invalid', we do not have a complete path, thus false results.

But, if we have 2 paths:
path 1: a-b-c
path 2: a-d-c
if a or c is invalid, path will fail (false) returned. if b OR d is invalid (but a & c are good), path will succeed, since an alternate path exists. This will return true unless both b & d are invalid

Returns:

There is an optional argument, validPath. If a List is supplied, and the convoy route is successful, the path taken will be returned in this List. If this argument is null, it will be ignored. The returned List will contain only Province objects.

Algorithm:

we must call SuperConvoyPath evaluator twice. The first time, we check for successes, by not counting "uncertain" convoys. This is because we cannot easily distinguish a successfull path from an uncertain path.

The second time through (if we were not succesful), we check to see if we fail (no path), or if we are uncertain.


findPathBreadthFirst

protected boolean findPathBreadthFirst(Location src,
                                       Location dest,
                                       Location current,
                                       java.util.List path,
                                       Path.PathEvaluator pathEvaluator)
Generalized recursive Path-Finder, Breadth-First search.

The path evaluator decides WHICH locations to add to the list of

The first path found that meets criteria will be in 'path'


getMinDistance

public int getMinDistance(Province src,
                          Province dest)
Find shortest distance between src & dest. Note that this uses 'touching' adjacency, and that the cost of movement between any adjacent province is the same.

This will return -1 in the event that src and dest are not connected.

Null src/dest Provinces are not allowed


findAllSeaPaths

public static Province[][] findAllSeaPaths(Path.FAPEvaluator evaluator,
                                           Province src,
                                           Province dest)
Finds all sea paths from src to dest..

This will return a zero-length array iff src or dest is not adjacent to a sea or a convoyable coastal ("sea equivalent") province.

Otherwise, all possible unique paths are returned, subject to the evaluation constraints of the FAPEvaluator.

This is typically very fast. For standard map, gas->lvp takes about 0.155 ms on a P4/3.0ghz; 10 unique paths are found. More specific FAPEvaluator methods (e.g., that look for a Fleet) will be faster.



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