package nxm.ucl.inc;

/** Defines an interface for a class that will provide acces to subsets of a
    pipe's data. This enables a pipe to be passed to an implementing class and
    that class will take the pipe and cut it up into smaller data sets which
    will be stored to disk. <br>
    <br>
    Implementing classes also provide the ability to "play-back" the data that
    has already been saved to disk.<br>
    <br>
    Playback control methods:
    <pre>
      Play the cuts starting at a given...
                            index: {@link #playFromIndex(int)}
                            file:  {@link #playFromFile(String)}
                            time:  {@link #playFromTime(double)}
      
      Play a single file and stop: {@link #playSingleFile(String)}
      
      Pause/resume the playback:   {@link #pause()}/{@link #resume()}
      
      Stop playback:               {@link #stop()}
    </pre>
 
    @see nxm.ucl.prim.pipecuts
 
    @author  J. Czechowski IV / J. Hallam
    @version $Id: PipeCutsIF.java,v 1.4 2005/02/17 18:37:14 jxc Exp $
    @since   NeXtMidas 1.9.X
 */
public interface PipeCutsIF {
  /** Defines the information block for a cut file. */
  public interface CutFileInfo {
    /** Gets the start time of the file.

        @return The <b>approximate</b> start time of the file
                (in Modified Julian Seconds).
     */
    public double getStartTime();

    /** Gets the end time of the file.

        @return The <b>approximate</b> end time of the file
                (in Modified Julian Seconds).
     */
    public double getEndTime();

    /** Gets the name of the cut file.

        @return The name of the cut file.
     */
    public String getName();
  }
  
  /////////////////////////////////////////////////////////////////////////////
  // GENERAL METHODS
  /////////////////////////////////////////////////////////////////////////////
  
  /** Return the full file name of the <b>current</b> input source. If the
      input source is a pipe it will start with a <code>'_'</code>.
   
      @return The current input source.
   */
  public String getSourcePipe();

  /** Set the input source that will be split. This can be set to either a pipe
      (if <code><i>name</i></code> starts with <code>'_'</code>) or a file.
   
      @param name The name of the pipe or file to split.
   */
  public void setSourcePipe(String name);
  
  /** Clears the cuts list of <b>currently accessible</b> cut files.
   
      @see #getCutsList()
   */
  public void clearCuts();
  
  /** Get a list of all of the <b>currently accessible</b> cut files.
   
      @return The list of the <b>currently accessible</b> cut files in chronological
              order.
   
      @see #clearCuts()
   */
  public CutFileInfo[] getCutsList();
  
  /** Sets the list of all of <b>currently accessible</b> cut files.
   
      @param files The cut files (<b>must be in chronological order</b>).
   
      @see #clearCuts()
      @see #setCutsList(String[])
      @see #getCutsList()
   */
  public void setCutsList(CutFileInfo[] files);
  
  /** Sets the list of all of <b>currently accessible</b> cut files.
   
      @param files The names of the cut files (<b>must be in chronological
                   order</b>).
   
      @see #clearCuts()
      @see #setCutsList(PipeCutsIF.CutFileInfo[])
      @see #getCutsList()
   */
  public void setCutsList(String[] files);
  
  /** Get the name of the current cut file.
   
      @return The name of the current cut file.
   */
  public String getActiveCut();
  
  /** Get the current file name prefix being used when generating the names for
      new cut files.
   
      @return The prefix in use.
   
      @see #setPrefix(String)
   */
  public String getPrefix();

  /** Set the current file name prefix to be used when generating the names for
      new cut files. This will not alter the names of any files that have been
      created.
   
      @param prefix The prefix in use.
   
      @see #getPrefix()
   */
  public void setPrefix(String prefix);
  
  /** Get the <b>approximate</b> length of each <b>new</b> cut file in Modified
      Julian Seconds.
   
      @return The <b>approximate</b> file duration in Modified Julian Seconds.
   
      @see #setCutFileInterval(double)
   */
  public double getCutFileInterval();

  /** Set the approximate length of each new cut file in Modified Julian
      Seconds. This will not alter the duration of any file that has already
      been created.
   
      @param duration The file duration in Modified Julian Seconds.
   
      @see #getCutFileInterval()
   */
  public void setCutFileInterval(double duration);

  /** Set RealTime transfer rate for when reading from a file.
   
      @param value The transfer rate in bytes/sec.
   */
  public void setReadRate(double value);
  
  //////////////////////////////////////////////////////////////////////////////
  // PLAYBACK CONTROL
  //////////////////////////////////////////////////////////////////////////////
  
  /** This will temporarially stop the output pipe but leave it in a state where
      is can be resumed (see {@link #resume()}) from the current location in the
      playback file. If the output pipe is currently connected to the input pipe
      this will not save the current position information (in this case calling
      {@link #resume()} will reconnect to the input pipe). <br>
      <br>
      This method makes no changes to the input pipe.
   
      @see #resume()
   */
  public void pause();
  
  /** This will resume a "paused" output pipe (see {@link #pause()}). If the
      output pipe was coming from a file this will resume reading the file at
      the point where {@link #pause()} was called. If the output was coming from
      the input pipe when {@link #pause()} was called this method will simply
      reconnect to the input pipe.<br>
      <br>
      This method makes no changes to the input pipe.
   
      @see #pause()
   */
  public void resume();
  
  /** This will stop the output pipe. Unlike {@link #pause()} this method does
      not allow the output to be resumed with the {@link #resume()} method since
      it closes the current file.
   
      @see #pause()
   */
  public void stop();
  
  /** This will play back a single file to the output pipe and then stop.
   
      @param filename The name of the file to play back.
   */
  public void playSingleFile(String filename);
  
  /** Opens the specified cut file for playback to the output pipe. <br>
      <br>
      If <code><i>file</i></code> is not in the list of cut files (see
      {@link #getCutsList()}) then the file will be played back until
      its end and then "real time" mode will be resumed. If
      <code><i>file</i></code> is in the list of cut files then once the file
      has played the next file in the cut list will be played, and so on.
      
      @param filename The name of the file to play back.
   
      @see #playFromIndex(int)
      @see #playFromTime(double)
   */
  public void playFromFile(String filename);
  
  
  /** Opens the specified cut file from the list of cut files for playback to
      the output pipe.
   
      @param index The index of the cut file in the list of cut files (see
                   {@link #getCutsList()}). Special values:
                   <pre>
                     <i>index</i> &lt; 0 -- Resume "real time" mode.
                     <i>index</i> = 0 -- Start with first cut.
                     <i>index</i> &gt; <i>n</i> -- Resume "real time" mode.
   
                     (<i>n</i> is the index of the last cut)
                   </pre>
   
      @see #playFromFile(String)
      @see #playFromTime(double)
   */
  public void playFromIndex(int index);
  
  /** Opens the specified cut file from the list of cut files based on a given
      time index for playback to the output pipe. This will open the first cut
      file in the list of cut files that ends <u>after</u>
      <code><i>time</i></code>.
      
      @param time  The time index (in Modified Julian Seconds) to get the cut
                   file for. Special values:
                   <pre>
                     <i>index</i> &lt; 0 -- Resume "real time" mode.
                     <i>index</i> = 0 -- Start with first cut.
                     <i>index</i> &gt; <i>t</i> -- Resume "real time" mode.
   
                     (<i>t</i> is the end time of the last cut)
                   </pre>
   
      @see #playFromIndex(int)
      @see #playFromFile(String)
   */
  public void playFromTime(double time);
}
