org.daisy.dotify.common.splitter.SplitPointDataSource Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dotify.common Show documentation
Dotify Common
The newest version!
package org.daisy.dotify.common.splitter;

import java.util.Collections;
import java.util.List;

/**
 * Provides split point data source. Data provided by via this interface
 * is expected to be immutable. The interface is designed to work with
 * data sources of unknown size. Access to the interfaces methods should
 * be done with care to limit unnecessary computation in the data source.
 * 
 * @author Joel Håkansson
 *
 * @param  the type of split point units
 * @param  the type of data source
 */
public interface SplitPointDataSource> {

	/**
	 * Gets the item at index.
	 * @param index the index
	 * @return returns the item
	 * @throws IndexOutOfBoundsException if the index is beyond the end of the stream
	 */
	public T get(int index);

	/**
	 * Gets all remaining items. Note that using this method will
	 * result in all elements being computed, if this is not what
	 * is needed. Consider using {@link #split(int)} instead.
	 * @return returns all remaining items
	 */
	public List getRemaining();

	/**
	 * Creates a new empty data source of the implementing type
	 * @return returns a new empty data source of the implementing type
	 */
	public U createEmpty();
	
	/**
	 * Gets the result of splitting at the specified index.
	 * An implementation must be able to handle indexes where
	 * {@link #hasElementAt(int)} returns false.
	 * 
	 * If atIndex is 0, the head of the result is empty and the
	 * original stream is in the tail. Conversely, if atIndex is greater
	 * than {@link #hasElementAt(int)} the  head of the result contains 
	 * {@link #getRemaining()} and the tail is empty.
	 * 
	 * @param atIndex the index where the tail starts
	 * @return returns a split result at the specified index
	 */
	public default SplitResult split(int atIndex) {
		if (atIndex==0) {
			return new DefaultSplitResult(Collections.emptyList(), getDataSource());
		} else if (hasElementAt(atIndex-1)) {
			return splitInRange(atIndex);
		} else {
			return new DefaultSplitResult<>(getRemaining(), createEmpty());
		}
	}
	
	/**
	 * Gets the result of splitting at the specified index.
	 * 
	 * @param atIndex the index where the tail starts
	 * @return returns a split result at the specified index
	 * @throws IndexOutOfBoundsException if the index isn't within the bounds of
	 * 			available data.
	 */
	public SplitResult splitInRange(int atIndex);
	
	/**
	 * Gets the data source as is, typically "return this" 
	 * @return returns the data source
	 */
	public U getDataSource();
	
	/**
	 * Returns true if the manager has an element at the specified index
	 * @param index the index
	 * @return returns true if the manager has an element at the specified index, false otherwise
	 */
	public boolean hasElementAt(int index);
	
	/**
	 * Gets the size of the manager or the limit if the number of items is greater than the limit
	 * @param limit the limit
	 * @return returns the size, or the limit
	 */
	public int getSize(int limit);
	
	/**
	 * Returns true if the manager contains no items. Note that
	 * this method can returns true, even if {@link #getSupplements()} is
	 * non-empty.
	 * @return returns true if the manager has no items, false otherwise
	 */
	public boolean isEmpty();
	
	/**
	 * Gets the split point data source supplements.
	 * @return the supplements
	 */
	public Supplements getSupplements();

}