package ie.dcu.segment;

import ie.dcu.segment.SegmentationContext;
import ie.dcu.segment.annotate.Annotation;
import ie.dcu.segment.options.Option;
import ie.dcu.segment.util.AbstractSegmenter;

import java.util.Collection;

/**
 * The interface that interactive segmentation algorithms are required to
 * implement.
 * 
 * Algorithm implementors can alternatively extend the {@link AbstractSegmenter}
 * class.
 * 
 * 
 * @author Kevin McGuinness
 * @version 1.1
 */
public interface Segmenter {
	
	/**
	 * Implementors should return <code>true</code> if the segmentation is
	 * available on the current platform. If, for example, the segmentation
	 * algorithm requires native libraries, and there are no such libraries
	 * compiled for the current platform, this method should return
	 * <code>false</code>.
	 * 
	 * @return <code>true</code> if the algorithm is available on this platform,
	 *         <code>false</code> otherwise.
	 */
	public boolean isAvailable();

	/**
	 * Returns the name of the segmentation algorithm.
	 * 
	 * @return The segmentation algorithm name. (never <code>null</code>).
	 */
	public String getName();


	/**
	 * Returns a short description of the segmentation algorithm.
	 * 
	 * @return A description (never <code>null</code>).
	 */
	public String getDescription();
	
	
	/**
	 * Returns the name of the author or vendor.
	 * 
	 * @return The vendor.
	 */
	public String getVendor();
	
	
	/**
	 * Returns <code>true</code> if the algorithm is "fast". Implementors should 
	 * return <code>true</code> if a call to update typically takes less that a
	 * second. Otherwise <code>false</code> should be returned. If the speed varies
	 * or you are unsure, return <code>false</code>.
	 * 
	 * @return <code>true</code> if the algorithm performs fast updates.
	 */
	public boolean isFast();
	
	
	/**
	 * Get the options (parameters) for the algorithm. This method may return an
	 * empty collection, but may not return <code>null</code>.
	 * 
	 * @return A collection of configurable options.
	 */
	public Collection<Option<?>> getOptions();


	/**
	 * Initialize a new segmentation. This method is provided to
	 * allow algorithms to initialize any data structures needed
	 * for segmentation and to perform any pre-segmentation 
	 * necessary.
	 * 
	 * @param ctx
	 *          The segmentation context.
	 */
	public void init(SegmentationContext ctx);


	/**
	 * Do a full update of the segmentation based on the current context.
	 * 
	 * @param ctx
	 *          The segmentation context.
	 */
	public void update(SegmentationContext ctx);


	/**
	 * Perform an incremental update when a single annotation is added to the
	 * context. This method is provided for algorithms that can improve
	 * performance by only updating based on the last annotation change.
	 * 
	 * @param ctx
	 *          The segmentation context.
	 * @param a
	 *          The last annotation.
	 */
	public void added(SegmentationContext ctx, Annotation a);


	/**
	 * Perform an incremental update when a single annotation is removed from the
	 * context. This method is provided for algorithms that can improve
	 * performance by only updating based on the last annotation change.
	 * 
	 * @param ctx
	 *          The segmentation context.
	 * @param a
	 *          The removed annotation.
	 */
	public void removed(SegmentationContext ctx, Annotation a);


	/**
	 * Perform any operations required before moving on to the next segmentation
	 * context. This method is provided to allow algorithms to dispose of any
	 * internal data structures or resources.
	 * 
	 * @param ctx The segmentation context.
	 */
	public void finish(SegmentationContext ctx);
	
	
}