/*
 * $Id: SGTData.java,v 1.9 2001/10/10 19:05:01 dwd Exp $
 *
 * This software is provided by NOAA for full, free and open release.  It is
 * understood by the recipient/user that NOAA assumes no liability for any
 * errors contained in the code.  Although this software is released without
 * conditions or restrictions in its use, it is expected that appropriate
 * credit be given to its author and to the National Oceanic and Atmospheric
 * Administration should the software be included by the recipient as an
 * element in other product development.
 */

package sgtplot.dm;


import java.beans.PropertyChangeListener;

import sgtplot.SGLabel;
import sgtplot.util.SoTRange;

/**
 * Base class for sgtplot datamodel rank information.
 * The SGTData class and its children are used by sgtplot
 * to determine the rank (point, line, grid) of the
 * data. Data values can be either double or
 * GeoDate, which extends Date.  Missing
 * values are indicated by Double.NaN for type
 * double and by null or by
 * Long.MIN_VALUE milliseconds after (before) January 1,
 * 1970 00:00:00 GMT for GeoDate.
 *
 * @author Donald Denbo
 * @version $Revision: 1.9 $, $Date: 2001/10/10 19:05:01 $
 * @since 1.0
 * @see SGTPoint
 * @see SGTLine
 * @see SGTGrid
 */
public interface SGTData {
  /**
   * Get the title.
   */
  public String getTitle();
  /**
   * Get a title formatted for a Key. JPlotLayout will use this
   * if an explicit Key title is not given in the addData method.
   *
   * @see sgtplot.SGLabel
   * @see sgtplot.ColorKey
   * @see sgtplot.LineKey
   * @see sgtplot.PointCollectionKey
   * @see sgtplot.VectorKey
   */
   public SGLabel getKeyTitle();
  /**
   * Get the unique identifier.  The presence of the identifier
   * is optional, but if it is present it should be unique.  This
   * field is used to search for the layer that contains the data.
   *
   * @return unique identifier
   * @see sgtplot.Pane
   * @see sgtplot.Layer
   */
  public String getId();
  /**
   * Create a shallow copy. User should implement using the clone()
   * method, which requires the Cloneable interface be inherited.
   * If clone() is used, then references to objects are copied NOT
   * the object itself.
   *
   * 
For example, 
   * 
   * public SGTData copy() {
   *   SGTData newData;
   *   try {
   *     newData = (SGTData)clone();
   *   } catch (CloneNotSupportedException e) {
   *     newData = null;
   *   }
   *   return newData;
   * }
   * 
   *
   * @return shallow copy
   * @see java.lang.Object
   */
  public SGTData copy();

  /**
   * Returns true if the X coordinate is Time.
   */
  public boolean isXTime();

  /**
   * Returns true if the Y coordinate is Time.
   */
  public boolean isYTime();

  /**
   * Returns the X SGTMetaData.
   */
  public SGTMetaData getXMetaData();

  /**
   * Returns the Y SGTMetaData.
   */
  public SGTMetaData getYMetaData();

  /**
   * Returns the range of the X coordinates.  If all the data in the
   * array is missing, this method will return Double.NaN
   * as the start and end values for data of type double
   * and return GeoDate(Long.MIN_VALUE) for data of type
   * GeoDate.
   *
   * @see sgtplot.util.GeoDate#isMissing()
   */
  public SoTRange getXRange();

  /**
   * Returns the range of the Y coordinates.
   * @see #getXRange()
   */
  public SoTRange getYRange();

  /**
   * Add a PropertyChangeListener to the listener list.
   */
  public void addPropertyChangeListener(PropertyChangeListener l);

  /**
   * Remove a PropertyChangeListener from the listener list.
   */
  public void removePropertyChangeListener(PropertyChangeListener l);
}