aQute.bnd.service.progress.ProgressPlugin Maven / Gradle / Ivy

package aQute.bnd.service.progress;


/**
 * A plugin for reporting progress on long-running jobs.
 * 
 * @author Neil Bartlett 
 */
public interface ProgressPlugin {

	/**
	 * Start a task with the specified name.
	 * 
	 * @param name
	 *            The name of the task -- must not be null.
	 * @param size
	 *            The expected size of the task, or -1 if not known in advance.
	 * @return A handle for the ongoing task.
	 */
	Task startTask(String name, int size);

	/**
	 * Represents an ongoing task.
	 */
	static interface Task {
		/**
		 * The specified number of units out of the total have been worked. If
		 * called after {@code done()}, an {@link IllegalStateException} may be
		 * thrown.
		 * 
		 * @param units
		 */
		void worked(int units);

		/**
		 * The task has been completed; optionally with a message and/or
		 * exception to indicate the outcome. After calling this method, no more
		 * work should be performed in the task.
		 * 
		 * @param message
		 *            A message associated with the completion of the task; may
		 *            be null.
		 * @param e
		 *            An exception thrown by the task; may be null;
		 */
		void done(String message, Throwable e);
	}

}