/*
 * Copyright (c) 2011, Patrik Dufresne. All rights reserved.
 * Patrik Dufresne PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
package com.planimod.core;

/**
 * The IGeneratePlanifProgressMonitor interface is implemented by objects that
 * monitor the creation of a planif.
 * 
 * A request to cancel an operation can be signaled using the setCanceled
 * method. Operations taking a progress monitor are expected to poll the monitor
 * (using isCanceled) periodically and abort at their earliest convenience.
 * Operation can however choose to ignore cancelation requests. Since
 * notification is synchronous with the activity itself, the listener should
 * provide a fast and robust implementation. If the handling of notifications
 * would involve blocking operations, or operations which might throw uncaught
 * exceptions, the notifications should be queued, and the actual processing
 * deferred (or perhaps delegated to a separate thread).
 * 
 * 
 * @author Patrik Dufresne
 * 
 */
public interface IGeneratePlanifProgressMonitor {
	/**
	 * Step creating the variables.
	 */
	public static final int STEP_CREATE_VARIABLES = 1;
	/**
	 * Step maximizing the number of assigned task.
	 */
	public static final int STEP_MAXIMIZE_ASSIGNED_TASK = 2;
	/**
	 * Step minimizing the number of required employee
	 */
	public static final int STEP_MINIMIZE_EMPLOYEE = 3;
	/**
	 * Step maximizing the senior employees
	 */
	public static final int STEP_MAXIMIZE_SENIOR = 4;
	/**
	 * Step maximizing the preferences.
	 */
	public static final int STEP_MAXIMIZE_PREFERENCES = 5;

	/**
	 * Notifies that the search for a solution is beginning. This is only called
	 * once for a given progress monitor instance.
	 * 
	 * @param work
	 *            total number of work
	 */
	public void beginSearch(int work);

	/**
	 * Notifies that the search as complete; that is, either the main task is
	 * completed or the user canceled it. This method may be called more than
	 * once (implementations should be prepared to handle this case).
	 */
	public void done();

	/**
	 * Returns whether cancelation of current operation has been requested.
	 * Long-running operations should poll to see if cancelation has been
	 * requested.
	 * 
	 * @return <code>true</code> if cancellation has been requested, and
	 *         <code>false</code> otherwise
	 * @see #setCanceled(boolean)
	 */
	public boolean isCanceled();

	/**
	 * Notifies the monitor about the current step being computed. The value of
	 * <code>step</code> should be one of the STEP_* constants.
	 * 
	 * @param step
	 *            the step
	 */
	public void setStep(int step);

	/**
	 * Notifies that a given number of work unit of the search has been
	 * completed. Note that this amount represents an installment, as opposed to
	 * a cumulative amount of work done to date.
	 * 
	 * @param work
	 *            a non-negative number of work units just completed
	 */
	public void worked(int work);

	/**
	 * The problem is unfeasible most probably because there is too many
	 * production events for the number of available employees. This function is
	 * called to request the user to continue or not.
	 * 
	 * @return True to continue, false to stop.
	 */
	public boolean callbackContinue();

}
