core
Class Search<T>

java.lang.Object
  extended by core.Search<T>
Type Parameters:
T - the specific type of all elements of the search domain.
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
BidirectionalSearch, DepthFirstSearch, DepthLimitedSearch, DirectedSearch, IterativeDeepeningAStar, IterativeDeepeningSearch, UndirectedSearch

public abstract class Search<T>
extends java.lang.Object
implements java.lang.Runnable

This Class is the abstraction of every search algorithm in a generic domain. It is typically used to pass searches around and manipulate them where maximum generality is desired (like the Collection interface).
In general a user can run each search in two equivalent ways:


 Search<Integer> search = new MySearch(5);
 search.run();
 search.getResult(); // should return 42 
 
or:

 Search<Integer> search = new MySearch(5);
 if (search.initialize()){
  search.run();
  search.getResult(); // should return 42 
 }else{
  System.out.println("The search could not be initialized!");
 } 
 
Note: The search will only be executed if it can be initialized(). So an uninitialized search will first try to initialize itself before execution.

To implement a new search you just have to create a subclass of Search and implement the abstract methods in an appropriate way.
There are some important information for developers of a new subclasses: There are further implementation patterns for each subclass of Search:
  1. Checking preconditions: Before a search can be executed Search#canPrepare() is checked. This method should be used to check all preconditions of a search algorithm so that if Search#canPrepare() returned true, Search#prepare() and Search#search() will be executed without any exceptions.
    Example: return ( problem.initial() != null )
  2. Prepare a search: Before a search is executed Search#prepare() is called to prepare your search. In general this method should be used for time consuming preparation tasks, such as creating an index or clearing a hash, which should not effect the execution time of the Search#run() method it self.
    Which initialization should be done in the prepare() method and which inside the search() method depends only on the developer.
    Example: hash.clear()
  3. Incrementing the step counter: This class contains a special field named neededSteps. This field will be automatically set to zero whenever a search is initialized. You should increment this field during execution of the Search#search() method so users can see the progress of the your search.
    Example: neededSteps++;
  4. Stopping a search:
    To enable your subclass to terminate the execution whenever the user called Search#stop() you must check the Search#running() method during the execution of your search. This method will return false whenever the execution should be terminated.
    Example: if (! running() ) return;
  5. Yielding the solution: This class contains a special field named result. If your search finds a solution then you should store this solution of Type T into this field (by assigning the solution to it) before you terminate your search. The result will hold the solution until the Search#initialize() method is called again.
    Example: if ( problem.isGoal(state) ){ result=state; return; }
The following simple example shows most of the basic implementation patterns:

 public class MySearch extends Search{
  private Integer initial=null;
  public MySearch(Integer i) {
   initial=i; 
  }
  protected void search(){
   Integer current=initial;
   while(running()){                // (4.)
    neededSteps++;                  // (3.)
    current++;
    if (current % 42 == 0){         // (5.)
     result = i;
     break; 
    }
   }
  }
  protected void canPrepare(){ 
   return initial!=null;            // (1.)
  }
  protected void prepare() { 
   if (initial<0) initial=-initial; // (2.)
  } 
 } 
 

Author:
Eden_06
See Also:
DirectedSearch, UndirectedSearch

Field Summary
protected  int neededSteps
          holding the number of steps needed for the search
protected  T result
          holding the result of the search or null if nothing has been found yet
 
Constructor Summary
Search()
          Creates a new instance of an abstract search.
 
Method Summary
protected abstract  boolean canPrepare()
          This method is the hook for the preparation of the search and determines if the search can be initialized.
protected  void finalize()
          This method frees the search.
 T getResult()
          This method returns the generic solution in the domain of the search.
 boolean initialize()
          This method initializes the search if possible and if it is not already initialized.
 boolean initialized()
          This method tells you whether a search is initialized (and can be performed) or not.
 int neededSteps()
          This method returns the number of steps the search needed to find a solution or zero if the search was not yet successful.
protected abstract  void prepare()
          This method is the hook for the preparation of the search and will be called from inside the initialize method.
 void run()
          This method runs the search if it can be initialized.
 boolean running()
          This method returns true only if the search has been started and is not finished or stopped.
protected abstract  void search()
          This method is the hook for any concrete implementation of a search algorithm and will be called from inside the run method.
 void stop()
          This method stops a running search.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

neededSteps

protected int neededSteps
holding the number of steps needed for the search


result

protected T result
holding the result of the search or null if nothing has been found yet

Constructor Detail

Search

public Search()
Creates a new instance of an abstract search.

Method Detail

initialize

public final boolean initialize()
This method initializes the search if possible and if it is not already initialized. In detail it uses the method canPrepare to determine if the search can really be prepared. Afterwards it uses the method prepare to initialize the search.

Returns:
true if the search is successfully initialized otherwise false

initialized

public final boolean initialized()
This method tells you whether a search is initialized (and can be performed) or not.

Returns:
true if the search has been initialized

run

public final void run()
This method runs the search if it can be initialized. After running this method initialized is set to false again.
Note: This method will also call the initialize() method, so you do not have to initialize a search.

Specified by:
run in interface java.lang.Runnable

stop

public final void stop()
This method stops a running search. In detail it sets an internal flag, which tells the search that it should terminate.


running

public final boolean running()
This method returns true only if the search has been started and is not finished or stopped.
Note: Every Subclass should call the running() method subsequently during a search and abort the search if it returned false.

Returns:
true only if the search has been started and is neither stopped nor finished

getResult

public final T getResult()
This method returns the generic solution in the domain of the search. or null if the search was not yet successful.

Returns:
a solution of the generic type T or null

neededSteps

public final int neededSteps()
This method returns the number of steps the search needed to find a solution or zero if the search was not yet successful.
Note: In respective to some search algorithms it may not return the number of cycles during the computation.

Returns:
the number of steps or zero

search

protected abstract void search()
This method is the hook for any concrete implementation of a search algorithm and will be called from inside the run method.
Note: The variable result and neededSteps must be set in this method in an appropriate way, to ensure that the result contain the solution or null if no solution was found.


canPrepare

protected abstract boolean canPrepare()
This method is the hook for the preparation of the search and determines if the search can be initialized. Use this method only to check the constraints for your search.
Note: Do not make preparation for the search in this method use the prepare method.

Returns:
true if the search can be prepared

prepare

protected abstract void prepare()
This method is the hook for the preparation of the search and will be called from inside the initialize method.
Note: The contract of the implementation of the initialize method ensures that prepare is only called when canPrepare returns true previously. So you must not check any constraints from the canPrepare method.
Warning: It is prohibited for this method to throw any kind of Exception!


finalize

protected void finalize()
                 throws java.lang.Throwable
This method frees the search.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable