package nxm.sys.inc;

import nxm.sys.lib.Table;

/** A read/write file with record-based data.

    @author  J. Czechowski IV
    @version $Id: RecordFileRW.java,v 1.3 2014/10/21 18:37:25 ntn Exp $
    @since   NeXtMidas 2.5.4
 */
interface RecordFileRW extends RecordFile {

  /** Sets a WHOLE row (or frame) in the file. The table should be in the form
      <code>{COL1=VAL1,COL2=VAL2,...,COLn=VALn}</code> where <code>COLx</code> is the name of
      the column (which matches {@link #getRecordDef(int)}) and <code>VALx</code> is the associated
      value.<br>
      <br>
      <b>Note:</b> The table does not need to exactly match the file format one-for-one. If the
      table includes "extra" filed (ones not in the file), those fields will just be ignored. If
      the table has "missing" fields (ones in the file but not the table) this method will just
      insert default values in for those "missing" fields (usually <code>0</code> or
      <code>""</code>, but this is implementation dependent).<br>
      <br>
      <b>Note:</b> If the offset given is beyond the end of the file, new rows (with default values)
      will be added as appropriate (e.g. if 100 used for a file with 75 elements [rows 0..74], this
      will add blank rows 75-99 and then add the new row as row 100).
      @param table  Input table, must match record structure.
      @param offset Offset into the file (0..n-1 or n, where n = add to end).
      @return Number of elements written or status.
   */
  int setData (double offset, Table table);

  /** Set a SINGLE ELEMENT of an existing row in the file. When this method is used no other
      elements in the given row are altered. Note that <code>fieldName</code> must match one
      of the columns in the file.
      @param element   The index of the element to set.
      @param fieldName The name of the field.
      @param obj       The data for the field.
   */
  void setData (double element, String fieldName, Object obj);

  /** Inserts a row (or frame) in the file. This method inserts a blank row in the file (shifting
      other rows down, as appropriate) and then uses {@link #setData(double,Table)} to set the data
      in the newly-created row.
      @param offset The offset (0 to n-1) into the file where the new element will be inserted,
                    use -1 to insert at end of the file.
      @param obj    The data to insert.
      @see #setData(double,Table)
   */
  void insertData (double offset, Object obj);

  /** Removes a row (or frame) from the file. Since NeXtMidas 2.1.3 this is the same as
      <code>removeData(offset,1L)</code>.
      @param offset The offset (0 to n-1) into the file where the element will be removed from.
   */
  void removeData (double offset);

  /** Removes a set of rows (or frames) from the file. If <code>count</code> is positive, this
      method shifts all rows after <code>offset</code> up by <code>count</code>, if count is
      <code>-1</code> all rows after <code>offset</code> are removed.
      @param offset The offset (0 to n-1) into the file of the first element to remove.
      @param count  The number of elements to remove or -1 to remove all elements starting at
                    offset. If count is 0, this method just returns normally without doing
                    anything.
   */
  void removeData (double offset, long count);

  /** Sets all of the record/column definitions for the file.
      <code>getRecordDef(i)</code>.
      @param defs The new record definitions; same syntax as used in {@link #getRecordDefs()}.
   */
  void setRecordDefs (Table defs);

  /** Update header(s) for data. Since NeXtMidas 3.1.1 */
  void update ();
}
