package nxm.sys.inc;

/** A class to define all file methods needed by Plot.

    @author  Jeff Schoen
 */
public interface PlotFile extends FrameFile, PlotFileModSwap {

  /** PLOT types list - moved in NeXtMidas 3.9.2*/
  public static final String typeList = "LINE,RASTER,CONTOUR,MESH,POINT,DOT";

  /** Plot constants that need to be available throughout NeXtMidas.
   *  @since NeXtMidas 3.9.2
   */
  public static final int T_LINE=1,T_RASTER=2,T_CONT=3,T_MESH=4,T_POINT=5,T_DOT=6;

  /** Initialize the data header fields.
      @param ref      The reference to use (usually an instance of {@link nxm.sys.lib.Midas} or
                      {@link nxm.sys.lib.Primitive}).
      @param filename The name of the file to use.
   */
  void init (Object ref, Object filename); // remove?

  /** Get the value of a specific qualifiers from the file's file name.  Returns the qualifier
      value associated with the key.
      @param key The qualifier's key.
      @return The value of the qualifier or null if not found.
   */
  Object getQualifier (String key); // remove?

  /** Get the time in seconds since 1 January 1950 at a given offset.
      @param offset The offset at which to get the time. For piped data, this can be negative, -N,
                    in order to get the time N frames prior to the current pipe position (e.g. if
                    the most recent element was 1000, <code>getTimeAt(-10)</code> is the same as
                    <code>getTimeAt(990)</code>). The use of -N is an advanced feature used in
                    conjunction with NeXtMidas pipes since it allows traversing pipe restarts
                    (this is handled in {@link nxm.sys.lib.DataFile#getTimeAt(double)}).
      @return The time in seconds since 1 Jan 1950.
      @see nxm.sys.lib.Time
   */
  double getTimeAt (double offset);

  /** Test for the existence of the file for a given read/write direction.
      @param dir The {@link nxm.sys.lib.IOResource} direction value (see comments at top of
                 {@link nxm.sys.lib.IOResource} for details.
      @return <code>true</code> if the file exists, <code>false</code> if not.
   */
  boolean find (int dir);

  /** Modify the connection (attach/detach from pipe). In cases where a pipe is not involved,
      this is simply an empty method (i.e. only {@link nxm.sys.lib.DataFile} implements this method).
      @param mode See {@link nxm.sys.lib.PipeResource#connect(int)} for details.
   */
  void connect (int mode);

  /** Gets the file type for a BLUE file.
      @return The file type (e.g. 1000, 2000, etc.)
   */
  int getType ();

  /** Get scalars per atom (also called SPA or mode) for the file.
      @return The number of scalars per atom for the file.
      @see nxm.sys.lib.Data#getSPA(byte)
   */
  int getMode ();

  /** Get the file tag to used.
      @return The "TAG" for the file (this is usually the root name of the file or specified using
              the <code>{TAG=...}</code> qualifier).
   */
  String getTag ();

  /** Tells if the I/O resource being used is a stream. Use {@link #isStreaming()} to determine if
      a stream is flowing.
      @return true if a stream is being used, false otherwise.
   */
  boolean isStream ();

  /** Tells if the I/O resource is streaming data.
      @return true if the resource is streaming, false otherwise. (This will always be false if
              {@link #isStream()} is false.)
   */
  boolean isStreaming ();

  /** Get the start value for the data from the file's header. Usually the same as {@link #getXStart()};
      in cases where Y is dominant (e.g. a Type 2000 BLUE File) {@link #getYStart()} is returned.
      @see nxm.sys.lib.DataFile#getStart()
      @return the start value for the data from the file's header.
   */
  double getStart ();

  /** Get the delta value for the data from the file's header. Usually the same as {@link #getXDelta()};
      in cases where Y is dominant (e.g. a Type 2000 BLUE File) {@link #getYDelta()} is returned.
      @see nxm.sys.lib.DataFile#getDelta()
      @return the delta value for the data from the file's header.
   */
  double getDelta ();

  /** Get the units for the data from the file's header. Usually the same as {@link #getXUnits()};
      in cases where Y is dominant (e.g. a Type 2000 BLUE File) {@link #getYUnits()} is returned.
      @see nxm.sys.lib.DataFile#getUnits()
      @see Units
      @return the units for the data from the file's header.
   */
  int getUnits ();

  /** Get the start value for the x-axis data from the file's header.
      @return the start value for the x-axis data from the file's header.
   */
  double getXStart ();

  /** Get the delta value for the x-axis data from the file's header.
      @return the delta value for the x-axis data from the file's header.
   */
  double getXDelta ();

  /** Get the units for the x-axis data from the file's header.
      @return the units for the x-axis data from the file's header.
      @see Units
  */
  int getXUnits ();

  /** Get the number of elements in the X-direction.
      @return the number of elements in the X-direction.
   */
  int getXFrame ();

  /** Get the start value for the y-axis data from the file's header.
      @return the start value for the y-axis data from the file's header.
   */
  double getYStart ();

  /** Get the delta value for the y-axis data from the file's header.
      @return the delta value for the y-axis data from the file's header.
   */
  double getYDelta ();

  /** Get the units for the y-axis data from the file's header.
      @see Units
      @return the units for the y-axis data from the file's header.
   */
  int getYUnits ();

  /** Get the number of elements in the Y-direction.
      @return the number of elements in the Y-direction.
   */
  int getYFrame ();
}
