package eu.simstadt.nf4j.async;

import eu.simstadt.nf4j.FailedTransmissionException;

/**
 * An asynchronous job will be sent in a non-blocking fashion, so that the main thread can proceed after calling
 * the send() operation. It queries the status of its remote nF counterpart frequently in a separate thread, so that
 * the job operations don't have to wait. Every asynchronous job should maintain a list of job status listeners.
 * Every registered job status listener should be notified upon significant and new job status changes. 
 * 
 * @author Marcel Bruse
 */
public interface AsyncJob {

	/**
	 * Frequently queries the remote status of the nF export job and updates the local status accordingly.
	 * The queries will be performed asynchronously in a separate thread. Job status listener will be notified
	 * upon every new status change.
	 * 
	 * @param interval Amount of seconds to wait before the next status update request will be sent to the
	 * nF server.
	 *  
	 * @throws FailedTransmissionException If your job has not been sent yet, then you will get some of this. 
	 */
	public void poll(int interval) throws FailedTransmissionException;
	
	/**
	 * Cancels all ongoing asynchronous operations of this job as soon as possible. Operations to be canceled
	 * might be send, poll and download operations. 
	 */
	public void cancel();
	
	/**
	 * Registers a job status listener at this job. The listener will then be notified upon job status changes.
	 *   
	 * @param jobListener The job status listener to be registered at this job.
	 */
	public void addJobStatusListener(JobStatusListener jobListener);
	
	/**
	 * Unregisters a job status listener for this job. The listener will not be notified about job status changes
	 * anymore.
	 * 
	 * @param jobListener The job status listener to be unregistered.
	 */
	public void removeJobStatusListener(JobStatusListener jobListener);
	
	/**
	 * Once the status of this job changes, all registered job status listeners will be notified.
	 */
	public void notifyJobStatusListeners();
	
	/**
	 * Convenience method.
	 * 
	 * @return Returns true, if the job is definitely done.
	 */
	public boolean hasFinished();
	
	/**
	 * Convenience method.
	 * 
	 * @return Returns true, if the job was unable to recover from a serious problem.
	 */
	public boolean hasFailed();

	/**
	 * Asynchronous polling tasks may query this flag frequently in order to decide to proceed or not.
	 * 
	 * @return Returns true, if the polling task should continue polling for status updates.
	 */
	public boolean keepPolling();
	
	/**
	 * Calls updateStatus() for you, since updateStatus() is a protected method. This method is used by the
	 * asynchronous PollJobStatusTask class.
	 * 
	 * @throws FailedTransmissionException If something goes wrong during the update process, you will get some
	 * of this.  
	 */
	public void triggerStatusUpdate() throws FailedTransmissionException;
	
}