/*******************************************************************************
 * Copyright (c) 2010 Oak Ridge National Laboratory.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 ******************************************************************************/
package org.csstudio.swt.xygraph.dataprovider;

import org.csstudio.swt.xygraph.linearscale.Range;

/**
 * Interface for the data provider of trace. This gives the possibilities to implement 
 * different data provider, which could have different data source or data storage structure.
 * For example: the data source could be from user input, database, files, etc,. 
 * The storage structure could be array, queue, circular buffer, bucket buffer, etc,.
 * <p>
 * An API like
 * <code>
 *  public ISample[] getSamples()
 * </code>
 * would be much easier to use by the XY Graph, but it forces the data
 * provider to copy its samples into an array, which might be a performance
 * and memory problem if considerable amounts of data are held in some other
 * data structure that is more suitable to the application.
 * <p>
 * The API is therefore based on single-sample access, allowing the application
 * to store the samples in arbitrary data structures.
 * <p>
 * <b>Synchronization</b><br>
 * Since the application data might change dynamically, the XY Graph
 * <code>synchronizes</code> on the <code>IDataProvider</code> like this
 * to assert that the sample count does not change while accessing individual
 * samples:
 * <pre>
 * IDataProvider data = ...;
 * synchronized (data)
 * {
 *     int count = data.getSize();
 *     ...
 *     ... getSample(i) ...
 * }
 * </pre>
 * Implementations of the <code>IDataProvider</code> should likewise synchronize
 * on it whenever the data is changed, and other methods like
 * <code>getXDataMinMax</code> should probably be synchronized implementations.
 * 
 * @author Xihui Chen
 * @author Kay Kasemir (synchronization)
 */
public interface IDataProvider {

	/**Total number of samples.
	 * @return the size.
     * @see #getSample(int)
	 */
	public int getSize();

	/**Get sample by index
     * <p>
     * <b>Synchronization:</b> 
     * Since the data might change dynamically, <code>synchronize</code> on the
     * <code>IDataProvider</code> around calls to <code>getSize()</code>
     * and <code>getSample()</code>.
     *
	 * @param index Sample index, 0...<code>getSize()-1</code>
	 * @return the sample.
	 */
	public ISample getSample(int index);

	/**Get the minimum and maximum xdata.
	 * @return a range includes the min and max as lower and upper. 
	 * return null if there is no data.
	 */
	public Range getXDataMinMax();

	/**Get the minimum and maximum ydata.
	 * @return a range includes the min and max as lower and upper.
	 * return null if there is no data.
	 */
	public Range getYDataMinMax();

	/**
	 * @return true if data is ascending sorted on X axis; false otherwise 
	 */
	public boolean isChronological();

	/** @param listener New listener to notify when data changes */
	public void addDataProviderListener(
			final IDataProviderListener listener);

    /** @param listener Listener to no longer notify when data changes
     *  @return <code>true</code> if listener was known and removed
     */
	public boolean removeDataProviderListener(
			final IDataProviderListener listener);	
	
	/**
	 * @return true if the ISample have error information.
	 * @return
	 */
	public boolean hasErrors();

}