/*
 * Created on Nov 4, 2004
 * 
 */
package ws.prova.kernel;

import java.util.EventListener;

/**
 * Defines goal satisfaction protocol.
 *
 * @author seb
 * @version $Revision: 1.1 $
 * @see ws.prova.Communicator#consultAsync(SolutionListener l, java.lang.String, java.lang.Object[])
 */

public interface SolutionListener extends EventListener {

	/**
	 * Typesafe enumeration for the <code>Continuation</code> returned by nextResult()
	 *
	 * @see SolutionListener#nextResult()
	 */
	public static final class Continuation implements java.io.Serializable {
		private boolean value;

		/*
		 * the old private constructor trick - be warned
		 * that the constructor is bypassed in deserialization
		 */
		private Continuation(boolean v) {
			value = v;
		}

		/* in order for serialization to work */
		private Object readResolve() throws java.io.ObjectStreamException {
			return (value ? BACKTRACK : PRUNE);
		}

		/**
		 * Indicate that solver must backtrack into next solution
		 */
		public static final Continuation BACKTRACK = new Continuation(true);
		/**
		 * Indicate that solver can stop processing goal(s)
		 */
		public static final Continuation PRUNE = new Continuation(false);

		public String toString() {
			return (value ? "BACKTRACK" : "PRUNE");
		}
	}


	/**
	 * Called asycnhronously by solver with results, obliged to return whether
	 * should backtrack: <code>Continuation.BACKTRACK</code> into solution space
	 * or cut and fail: <code>Continuation.PRUNE</code>
	 *
	 * @param result - the result set
	 * @return Continuation
	 */
	public abstract Continuation nextResult(ProvaResultSet result);
}
