/**
 * IProgressTrackingStrategy.java
 * Created May 30, 2006
 * Copyright (C) Tandberg Television 2006
 */
package com.tandbergtv.workflow.driver.service;

import java.util.Date;

import org.jbpm.graph.exe.Token;

import com.tandbergtv.workflow.core.WorkflowProcess;
import com.tandbergtv.workflow.core.service.Service;

/**
 * Strategy to be used for estimating the duration and completion time of a workflow process
 * and individual steps within the process. Implementations are free to make guarantees about the 
 * accuracy of calculations.
 * 
 * @author Sahil Verma
 */
public interface IProgressTrackingStrategy extends Service {
	
	/**
	 * Returns a value indicating the expected time, from start to finish, that the
	 * specified process may take. If the process has finished, normally or abnormally,
	 * returns the actual time that was spent in execution.
	 * 
	 * @param process
	 * @return
	 */
	Date calculateTime(WorkflowProcess process);
	
	/**
	 * Returns a value indicating the expected time taken for the specified workflow step
	 * to complete. For some steps, this may be a simple constant. For others, the
	 * amount of time taken depends on certain input parameters, expected queue delays, or 
	 * in the case of manual tasks this value may be derived using guesswork.
	 * 
	 * @param token
	 * @return
	 */
	Date calculateTime(Token token);
	
	/**
	 * Returns a value indicating the minimum time that would be taken by the specified process
	 * to run from start to completion. This is a highly optimistic value that doesn't
	 * take into account branches, loops, queueing delays etc.
	 * 
	 * @param process
	 * @return
	 */
	Date calculateMinimumTime(WorkflowProcess process);
	
	/**
	 * Returns a value indicating the minimum time taken to complete the specified step.
	 *  
	 * @param token
	 * @return
	 */
	Date calculateMinimumTime(Token token);

	/**
	 * Returns a value indicating the maximum time that would be taken by the specified process
	 * to run from start to completion.
	 * 
	 * @param process
	 * @return
	 */
	Date calculateMaximumTime(WorkflowProcess process);
	
	/**
	 * Returns a value indicating the maximum time that would be taken by the specified step
	 * to run from start to completion.
	 * 
	 * @param token
	 * @return
	 */
	Date calculateMaximumTime(Token token);
	
	/**
	 * Calculates the amount of time left for the specified process to complete.
	 * 
	 * @param process
	 * @return
	 */
	Date calculateRemainingTime(WorkflowProcess process);
	
	/**
	 * Calculates the time remaining for the node that is pointed to by the specified token 
	 * to complete.
	 * 
	 * @param token
	 * @return
	 */
	Date calculateRemainingTime(Token token);
	
	/**
	 * Calculates the percentage completion of the node pointed to by the specified token.
	 * The caller is responsible for making sure that the token is part of a process that is
	 * actually running
	 * 
	 * @param token
	 * @return
	 */
	String calculatePercentComplete(Token token);
	
	/**
	 * Sets the completion percent
	 * @param token
	 * @param percent
	 */
	void setPercentComplete(Token token, String percent);
	
	/**
	 * Indicates that the step has completed 
	 * 
	 * @param token
	 */
	void setComplete(Token token);
}