Package org.cicirello.search.operators

Interface MutationIterator

  • public interface MutationIterator

    Defines an interface for iterating over all of the mutants (i.e., neighbors) of a candidate solution to a problem. MutationIterators are used in combination with IterableMutationOperator objects.

    Example 1: Here is an example of its use. In this first example, we iterate over all neighbors. At the completion of this block, the state of x will be as of the most recent call to setSavepoint() or its original state if that method was never called.

    
 T x = some object of type T.
 IterableMutationOperator<T> mutation = ....
 MutationIterator iter = mutation.iterator(x);
 while (iter.hasNext()) {
     iter.nextMutant();
     if (new state of x is one we'd like to be able to revert to) {
          iter.setSavepoint();
     } 
 }
 // This next statement rolls x back to the last savepoint.
 iter.rollback();

    Example 2: In this next example, we iterate over neighbors only until we find one we like.

    
 T x = some object of type T.
 IterableMutationOperator<T> mutation = ....
 MutationIterator iter = mutation.iterator(x);
 boolean foundOneToKeep = false;
 while (iter.hasNext()) {
     iter.nextMutant();
     if (new state of x is one we'd like to keep) {
          foundOneToKeep = true;
          break;
     } 
 }
 if (!foundOneToKeep) iter.rollback();

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean hasNext()
      Checks whether there are any additional neighbors of the candidate solution.
      void nextMutant()
      Mutates the candidate solution into its next neighbor.
      void rollback()
      Reverts the candidate solution to its state as of the most recent call to the setSavepoint() method, or its original state if that method has not been called.
      void setSavepoint()
      Records internally within the MutationIterator the current neighbor/mutant, enabling reverting back to this neighbor when the rollback() method is called.

    • Method Detail

      • hasNext

        boolean hasNext()
        Checks whether there are any additional neighbors of the candidate solution.
        Returns:
        true if there are additional neighbors that can be iterated over via the nextMutant() method, provided the rollback() method has not been called.

      • nextMutant

        void nextMutant()
        Mutates the candidate solution into its next neighbor.
        Throws:
        IllegalStateException - if there are no additional neighbors to iterate over or if the rollback() method was called. You should use the hasNext() method to check first.

      • setSavepoint

        void setSavepoint()
        Records internally within the MutationIterator the current neighbor/mutant, enabling reverting back to this neighbor when the rollback() method is called. This does not affect the order of neighbors returned by future calls to the nextMutant() method.

      • rollback

        void rollback()
        Reverts the candidate solution to its state as of the most recent call to the setSavepoint() method, or its original state if that method has not been called. Upon calling the rollback method, all future calls to the nextMutant() method will throw an IllegalStateException. If rollback is not called, then the candidate solution's state will be as of the most recent call to nextMutant().