mil.af.afit.uvr
Class HEngine

java.lang.Object
  |
  +--mil.af.afit.uvr.HEngine
All Implemented Interfaces:
mil.af.afit.uvr.HSolverListener

public class HEngine
extends java.lang.Object
implements mil.af.afit.uvr.HSolverListener

The HEngine is the main source of interaction between code that uses the Universal Vehicle Router (UVR) and the UVR itself. It accepts information about the vehicles and orders and tries to find a solution based on the parameters you specify. The default solver is the SolomonConstructionSolver. The default evaluator is the EvaluatorWithPriorities.

Since:
1.0
See Also:
HEngineEvent, HEngineListener, HEvaluator, HOrder, HVehicle, HSolution, EvaluatorWithPriorities, SolomonConstructionSolver

Field Summary
protected  java.util.Properties properties
           
static java.lang.String PROPERTIES_HEADER
           
static java.lang.String SOLVER_KEY_PREFIX
           
static java.lang.String UVR_PROPERTIES_DIR_KEY
           
static java.lang.String UVR_PROPERTIES_FILE_NAME
           
 
Constructor Summary
HEngine()
          Constructs an HEngine that is not yet aware of any orders or vehicles.
HEngine(HVehicle[] vehicles, HOrder[] orders)
          Constructs an HEngine based on the passed orders and vehicles.
HEngine(HVehicle[] vehicles, HOrder[] orders, int numberOfThreads)
          Constructs an HEngine based on the passed orders and vehicles and specifies the number of threads subsequent solvers should use.
HEngine(java.util.Properties prop)
          Constructs an HEngine that is not yet aware of any orders or vehicles.
 
Method Summary
 void addHEngineListener(HEngineListener listener)
          Add a listener to the engine.
protected static void err(java.lang.Exception e)
           
 java.util.Enumeration getAvailableSolvers()
          Returns an enumeration of HSolvers already known to the HEngine.
 HSolution getBestHSolution()
          Returns the best solution so far.
static java.util.Properties getDefaultProperties()
          Return the default properties for the HEngine.
 double getEffort()
          Returns the amount of effort that the HEngine will expend.
 HEvaluator getHEvaluator()
          Returns the evaluator being used.
 int getNumberOfThreads()
          Returns the number of threads that was requested for the solver to use.
 float getPercentDone()
          Returns the progress of the HEngine as a value between zero and one, inclusively.
 java.util.Properties getProperties()
          Returns the properties being used.
 double getRequestedSolutionEffort()
          Deprecated. Use getEffort().
 HSolver getSolver()
          Returns the solver that will be used or is being used by the HEngine.
 void HSolverEventPerformed(mil.af.afit.uvr.HSolverEvent e)
          Called when an HSolverEvent is fired.
 boolean isCanceled()
          Returns true if the user has tried to cancel the HEngine.
protected static void out(java.lang.Object obj)
           
 void removeHEngineListener(HEngineListener listener)
          Remove a listener from the engine.
protected  void setBestHSolution(HSolution soln)
          Used internally to set the best known solution
 double setEffort(double effort)
          Sets the requested effort.
 void setHEvaluator(HEvaluator evaluator)
          Sets the evaluator to use.
 void setHOrders(HOrder[] orders)
          Sets the orders to be served by the vehicles
 void setHVehicles(HVehicle[] vehicles)
          Sets the vehicles used to service the orders.
 void setNumberOfThreads(int numberOfThreads)
          Sets the suggested number of threads to use.
protected  void setPercentAlottedToSolomon(float percentAlotted)
          This determines how much of the progress is represented as coming from the HSolomon work.
 double setRequestedSolutionEffort(double effort)
          Deprecated. Use setEffort().
 void setSolver(HSolver solver)
          Sets the solver to be used by the HEngine.
 HSolver setSolver(java.lang.String solverName)
          Deprecated. Set the solver by using an actual HSolver object. If you must keep a String record of a solver, use the class name and then instantiate a new solver with Class.forName( strSolverClassName ).newInstance().
protected  void solomonReportingProgress(float progress)
          Used internally by HSolomon to report progress.
 void startSolving()
          Starts the HEngine solving in another thread.
 void stopSolving()
          Stops the HEngine.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UVR_PROPERTIES_DIR_KEY

public static final java.lang.String UVR_PROPERTIES_DIR_KEY

UVR_PROPERTIES_FILE_NAME

public static final java.lang.String UVR_PROPERTIES_FILE_NAME

SOLVER_KEY_PREFIX

public static final java.lang.String SOLVER_KEY_PREFIX

PROPERTIES_HEADER

public static final java.lang.String PROPERTIES_HEADER

properties

protected java.util.Properties properties
Constructor Detail

HEngine

public HEngine()
Constructs an HEngine that is not yet aware of any orders or vehicles. Since one of the things the HEngine does on construction is begin to load available solvers in another thread, it can be beneficial to use this constructor right before waiting for some user input.
Since:
1.0

HEngine

public HEngine(java.util.Properties prop)
Constructs an HEngine that is not yet aware of any orders or vehicles. The HEngine will start with the properties specified. Currently this is only used to specify which solvers to make available. The properties are stored in the following manner:

 uvr.solver.1=package.subpackage.solverclassname
 uvr.solver.2=otherpackage.subpack.subpacktoo.othersolverclassname
 

The HEngine will stop loading solvers when the sequence is broken.

Since:
1.0
See Also:
HSolver, Properties

HEngine

public HEngine(HVehicle[] vehicles,
               HOrder[] orders)
Constructs an HEngine based on the passed orders and vehicles.
Parameters:
vehicles - the vehicles to use
orders - the orders to use
Since:
1.0
See Also:
HVehicle, HOrder

HEngine

public HEngine(HVehicle[] vehicles,
               HOrder[] orders,
               int numberOfThreads)
Constructs an HEngine based on the passed orders and vehicles and specifies the number of threads subsequent solvers should use. This can be helpful on multiprocessor computers.
Parameters:
vehicles - the vehicles to use
orders - the orders to use
numberOfThreads - suggested number of threads to use
Since:
1.0
See Also:
HVehicle, HOrder
Method Detail

getDefaultProperties

public static final java.util.Properties getDefaultProperties()
Return the default properties for the HEngine. Use this to force the default solvers to load in case your uvr.properties file got messed up.
Returns:
default properties
Since:
1.0
See Also:
Properties

setPercentAlottedToSolomon

protected final void setPercentAlottedToSolomon(float percentAlotted)
This determines how much of the progress is represented as coming from the HSolomon work.
Parameters:
percentAlotted - how much of the overall progress is attributed to HSolomon
Since:
1.0

setRequestedSolutionEffort

public final double setRequestedSolutionEffort(double effort)
Deprecated. Use setEffort().

Sets the requested effort. Numbers less than zero or greater than one are set at zero and one, respectively. Less effort results in less work being done by the HEngine and thus reduces solve time.
Parameters:
effort - amount of effort to expend
return - the new effort setting
Since:
1.0

setEffort

public final double setEffort(double effort)
Sets the requested effort. Numbers less than zero or greater than one are set at zero and one, respectively. Less effort results in less work being done by the HEngine and thus reduces solve time.
Parameters:
effort - amount of effort to expend
return - the new effort setting
Since:
1.0.2

getRequestedSolutionEffort

public final double getRequestedSolutionEffort()
Deprecated. Use getEffort().

Returns the amount of effort that the HEngine will expend.
Returns:
effort
Since:
1.0

getEffort

public final double getEffort()
Returns the amount of effort that the HEngine will expend.
Returns:
effort
Since:
1.0.2

isCanceled

public final boolean isCanceled()
Returns true if the user has tried to cancel the HEngine.
Returns:
whether or not the user has tried to cancel the HEngine
Since:
1.0

stopSolving

public final void stopSolving()
Stops the HEngine. If in the middle of the tour-building heuristic, there may be a delay before the HEngine actually stops working. An event signaling that the engine has stopped will be fired.
Since:
1.0

startSolving

public final void startSolving()
Starts the HEngine solving in another thread. Control returns to the calling method immediately.
Since:
1.0

getAvailableSolvers

public final java.util.Enumeration getAvailableSolvers()
Returns an enumeration of HSolvers already known to the HEngine. You should never use the actual solver objects returned. Always create a new instance with something like the following:

 HEngine engine = new HEngine();
 Enumeration enum = engine.getAvailableSolvers();
 HSolver solverToUse = null;
 try
 {    solverToUse = (HSolver) enum.nextElement().getClass().newInstance();
 }    // end try
 catch( IllegalAccessException e ){}
 catch( InstantiationExceptione e ){}
 
Returns:
HSolvers known to the HEngine
Since:
1.0
See Also:
HSolver, Enumeration

getSolver

public final HSolver getSolver()
Returns the solver that will be used or is being used by the HEngine.
Returns:
current solver
Since:
1.0
See Also:
HSolver

setSolver

public final void setSolver(HSolver solver)
Sets the solver to be used by the HEngine. If the solver is different than any already in use, it is added to the engine's list.
Parameters:
solver - solver to use
Since:
1.0
See Also:
HSolver

setSolver

public final HSolver setSolver(java.lang.String solverName)
Deprecated. Set the solver by using an actual HSolver object. If you must keep a String record of a solver, use the class name and then instantiate a new solver with Class.forName( strSolverClassName ).newInstance().

Sets the solver to the one named solverName. For this to work, the appropriate solver must be one that would be returned by getAvailableSolvers().
Parameters:
solverName - name of solver to use
Since:
1.0
See Also:
HSolver

setHEvaluator

public final void setHEvaluator(HEvaluator evaluator)
Sets the evaluator to use.
Parameters:
evaluator - evaluator to use
Since:
1.0
See Also:
HEvaluator

setNumberOfThreads

public final void setNumberOfThreads(int numberOfThreads)
Sets the suggested number of threads to use.
Parameters:
numberOfThreads - number of suggested threads to use
Since:
1.0

getNumberOfThreads

public final int getNumberOfThreads()
Returns the number of threads that was requested for the solver to use.
Returns:
number of threads for the solver to use.
Since:
1.0.2

setBestHSolution

protected final void setBestHSolution(HSolution soln)
Used internally to set the best known solution
Parameters:
soln - best solution
Since:
1.0
See Also:
HSolution

getBestHSolution

public final HSolution getBestHSolution()
Returns the best solution so far.
Returns:
best solution so far
Since:
1.0
See Also:
HSolution

getHEvaluator

public final HEvaluator getHEvaluator()
Returns the evaluator being used.
Returns:
the evaluator being used
Since:
1.0
See Also:
HEvaluator

getProperties

public final java.util.Properties getProperties()
Returns the properties being used. Currently this only records solvers to try to load.
Returns:
properties being used
Since:
1.0
See Also:
HSolver, Properties

getPercentDone

public final float getPercentDone()
Returns the progress of the HEngine as a value between zero and one, inclusively.
Returns:
percent done
Since:
1.0

setHVehicles

public final void setHVehicles(HVehicle[] vehicles)
Sets the vehicles used to service the orders.
Parameters:
vehicles - the vehicles to use to server the orders
Since:
1.0
See Also:
HVehicle, HOrder

setHOrders

public final void setHOrders(HOrder[] orders)
Sets the orders to be served by the vehicles
Parameters:
orders - the orders to be served by the vehicles
Since:
1.0
See Also:
HOrder, HVehicle

solomonReportingProgress

protected final void solomonReportingProgress(float progress)
Used internally by HSolomon to report progress.
Parameters:
progress - progress between zero and one
Since:
1.0

HSolverEventPerformed

public void HSolverEventPerformed(mil.af.afit.uvr.HSolverEvent e)
Called when an HSolverEvent is fired.
Specified by:
HSolverEventPerformed in interface mil.af.afit.uvr.HSolverListener
Parameters:
e - event fired
Since:
1.0
See Also:
HSolverEvent, HSolverListener

addHEngineListener

public final void addHEngineListener(HEngineListener listener)
Add a listener to the engine. This listener will be notified when engine events happen.
Parameters:
listener - the listener to notify of engine events
Since:
1.0
See Also:
HEngineListener, HEngineEvent

removeHEngineListener

public final void removeHEngineListener(HEngineListener listener)
Remove a listener from the engine. This listener will no longer be notified when engine events happen.
Parameters:
listener - the listener which will no longer receive engine events
Since:
1.0
See Also:
HEngineListener, HEngineEvent

out

protected static final void out(java.lang.Object obj)

err

protected static final void err(java.lang.Exception e)