/*
 * Moonlight|3D Copyright (C) 2005 The Moonlight|3D team
 * 
 * This library is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation; either version 2.1 of the License, or (at your option)
 * any later version.
 * 
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 * 
 * Created on Nov 2, 2005
 */
package ml.core.tasks;

/**
 * Base class for all background tasks. Background
 * tasks should derive from the Task class and have
 * their execution controlled by the TaskManager class.
 * <br>
 * Background tasks are required to implement the run()
 * method. Since they usually are long-running in nature
 * they should query shouldTerminate() in regular intervals
 * to query if the user has requested to abort the task
 * and if so, try to abort the process gracefully if
 * possible. If aborting the task would leave the program
 * in a bad or undefined state then the request should
 * rather be ignored and the task left running until
 * a correct state is restored or the task has finished.
 * 
 * @author gregor
 */
public abstract class Task implements Runnable {
	private String name;
	private String actionDescription;
	private boolean shouldTerminate=false;
	private TaskManager manager;
	
	public Task(TaskManager manager)
	{
		this.manager=manager;
	}

	public abstract void run();
	
	/**
	 * This function should be called in regular intervals
	 * by the running task to determine if the graceful
	 * termination of this task has been requested by the
	 * user and if so, perform it as soon as possible.
	 * 
	 * @return true if the task should terminate as soon as
	 * reasonably possible
	 */
	public boolean shouldTerminate()
	{
		return shouldTerminate;
	}
	
	/**
	 * Request this task to terminate as soon as reasonably
	 * possible without corrupting program state.
	 *
	 */
	public void requestTermination()
	{
		shouldTerminate=true;
	}
	
	public TaskManager getTaskManager()
	{
		return manager;
	}
	
	/**
	 * Set the name of this task. This name should be
	 * brief, but descriptive because it is displayed
	 * to the user.
	 * 
	 * @param name the name of the task
	 */
	protected void setName(String name)
	{
		this.name=name;
	}
	
	/**
	 * Return a human-readable display name of this task,
	 * 
	 * @return name of this task
	 */
	public String getName()
	{
		return name;
	}
	
	/**
	 * Set a description of the current action this task performs.
	 * This is displayed as a hint for the user in order to estimate
	 * the status and progress of the task. Also notify all observers 
	 * of TaskManager of this change.
	 * 
	 * @param actionDescription the description to be displayed
	 */
	protected void setActionDescription(String actionDescription)
	{
		this.actionDescription=actionDescription;
		manager.notifyObservers();
	}

	/**
	 * Return a description of the current action of the task.
	 * 
	 * @return the current action description
	 */
	public String getActionDescription()
	{
		return actionDescription;
	}
}