core
Class DirectedSearch<T>

java.lang.Object
  extended by core.Search<T>
      extended by core.DirectedSearch<T>
Type Parameters:
T - the specific type of all elements of the search domain.
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
BestFirstSearch, BreadthFirstSearch, SlowDepthFirstSearch

public abstract class DirectedSearch<T>
extends Search<T>

This subclass of Search is the core implementation of most directed search algorithms and is able to perform many various directed search strategies such as depth first, breath first or best first search.
Inherent for all these algorithms is that the search space is explored in a tree based structure. To run a DirectedSearch there must be an instance of core.Problem given. (See description for further information.)
To avoid duplicate states during the search a HashSet is used, which tries to hash all expanded states in order to inhibit further expansion. In detail there are two important rules for states of type T which allow proper hashing:

In some cases it is important to turn of the implicit hashing. This can be done by simply creating a new instance of a directed search with the given argument noHash set to true.
Example: DirectedSearch<State> search = new BreadthFirstSearch<State>(problem, true);
This class defines the basic search algorithm which can be applied to some directed searches. This algorithm can be described in the following way:
  1. If empty() is true terminate the search.
  2. current = pop() get the next node from the queue.
  3. If isGoal(current) is true then save the current state and terminate the search.
  4. For each node in problem.expand(current) add(node) to the queue.
  5. Go to 1.
As Developer of a new directed search you only have to instantiate a queue and then implement the following queuing methods: This implementation does not catch any thrown exception, so make sure your methods do not throw exceptions in most of the cases.
(Of course OutOfMemoryException's can not be avoided.)

Author:
eden06
See Also:
BestFirstSearch, BreadthFirstSearch, SlowDepthFirstSearch

Field Summary
protected  java.util.Set<T> hash
          holds the set used for duplicate handling
protected  Problem<T> problem
          holds the problem to be solved during the search
 
Fields inherited from class core.Search
neededSteps, result
 
Constructor Summary
DirectedSearch(Problem<T> problem)
          Creates a new directed search with the given problem.
DirectedSearch(Problem<T> problem, boolean noHash)
          Creates a new directed search with the given problem and a flag indicating whether duplicate handling should be turned off.
 
Method Summary
protected abstract  boolean add(T state)
          This method is the hook for adding new states to the queue during the search.
 int branchedNodes()
          This method returns the number of expanded nodes during the search.
protected  boolean canPrepare()
          This method checks if the given problem returns a valid initial state.
protected abstract  void clear()
          This method is the hook for clearing the queue on preparation of a new search.
protected abstract  boolean empty()
          This method is the hook for the check if the queue is empty during the search.
protected  void finalize()
          This method frees the search.
 Problem<T> getProblem()
          This method returns the problem, with which this search has been created.
protected abstract  T pop()
          This method is the hook for extracting the first element of the queue during the search.
protected  void prepare()
          This method clears the queue and the hash used for duplicate handling to prepare them for a new search run.
protected  void search()
          This method looks for a goal in the search domain, by iteratively expanding the first state of the queue and adding all successor state to the queue.
 
Methods inherited from class core.Search
getResult, initialize, initialized, neededSteps, run, running, stop
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

problem

protected Problem<T> problem
holds the problem to be solved during the search


hash

protected java.util.Set<T> hash
holds the set used for duplicate handling

Constructor Detail

DirectedSearch

public DirectedSearch(Problem<T> problem)
               throws java.lang.IllegalArgumentException
Creates a new directed search with the given problem.

Parameters:
problem - to be solved
Throws:
java.lang.IllegalArgumentException - if the given problem is null

DirectedSearch

public DirectedSearch(Problem<T> problem,
                      boolean noHash)
               throws java.lang.IllegalArgumentException
Creates a new directed search with the given problem and a flag indicating whether duplicate handling should be turned off.

Parameters:
problem - to be solved
noHash - flag indicating that duplicates should not be handled
Throws:
java.lang.IllegalArgumentException - if the given problem is null
Method Detail

branchedNodes

public final int branchedNodes()
This method returns the number of expanded nodes during the search.
Note: This method is an alias for neededSteps() and has the same result.

Returns:
the number of expanded nodes

getProblem

public Problem<T> getProblem()
This method returns the problem, with which this search has been created.

Returns:
the problem to be solved

canPrepare

protected final boolean canPrepare()
This method checks if the given problem returns a valid initial state.

Specified by:
canPrepare in class Search<T>
Returns:
true if the search can be prepared
See Also:
Search.canPrepare()

finalize

protected final void finalize()
                       throws java.lang.Throwable
Description copied from class: Search
This method frees the search.

Overrides:
finalize in class Search<T>
Throws:
java.lang.Throwable
See Also:
Search.finalize()

prepare

protected final void prepare()
This method clears the queue and the hash used for duplicate handling to prepare them for a new search run.

Specified by:
prepare in class Search<T>
See Also:
Search.prepare()

search

protected final void search()
This method looks for a goal in the search domain, by iteratively expanding the first state of the queue and adding all successor state to the queue.
Note: A more accurate description is given in core.DirectedSearch.

Specified by:
search in class Search<T>
See Also:
Search.search()

add

protected abstract boolean add(T state)
This method is the hook for adding new states to the queue during the search.
After calling this method the state should be added to the queue.
Note: Most implementations do not check whether a state has been successfully added or not.

Parameters:
state - to be added to the queue
Returns:
true only if this state has been added.

pop

protected abstract T pop()
This method is the hook for extracting the first element of the queue during the search.
It should return and remove the first element of the queue.
Note: The implementation assures that this method will only be called if empty() returned false.

Returns:
the first element of the queue

clear

protected abstract void clear()
This method is the hook for clearing the queue on preparation of a new search.
It should remove all elements of the queue.


empty

protected abstract boolean empty()
This method is the hook for the check if the queue is empty during the search.
It should return true whenever the queue is empty.

Returns:
true only if the queue is empty.