/* Copyright (c) 2006 Ricebridge. All Rights Reserved.
 *
 * This file is available under the terms and conditions of the
 * Ricebridge "Open Source API" policy; Ricebridge grants use of this
 * copyrighted work under the terms of a BSD-style license only. See
 * http://www.opensource.org/licenses/bsd-license.php for more
 * information.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 *  - Redistributions of source code must retain the above copyright
 *  notice, this list of conditions and the following disclaimer.
 *
 *  - Redistributions in binary form must reproduce the above
 *  copyright notice, this list of conditions and the following
 *  disclaimer in the documentation and/or other materials provided
 *  with the distribution.
 *
 *  - Neither the name of the Ricebridge nor the names of its
 *  contributors may be used to endorse or promote products derived
 *  from this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.  
 */


package com.ricebridge.csvman;


/** Save CSV data lines as you create them.
 *    <p>This interface allows you to save CSV data lines as a stream of data, one at a time. Instead
 *  of saving an entire CSV file, as with the {@link CsvManager#save(Object,List) CsvManager.save} method, or
 *  implementing a {@link CustomLineProvider}, <code>CsvSaver</code> lets you provide the data
 *  directly using a push-style interface. Every time you have a line to save, you call the {@link #next next(String[])} method.</p> 

 *    <p>To start a save operation, use the {@link CsvManager#makeSaver(Object) CsvManager.makeSaver}
 *  method. This returns a <code>CsvSaver</code> object. Then use the following sequence
 *  of method calls:</p>
 *    <ul><li>{@link #begin} - required, tells the <code>CsvSaver</code> to open the data resource (usually a CSV file on disk)</li>
 *        <li>{@link #next next(String)} - required, provide the next line of data as a <code>String[]</code> array</li>
 *        <li>{@link #end} - required, tells the <code>CsvLoader</code> to close the data resource (usually a CSV file on disk)</li></ul>
 *    <p>Here is some example code:</p>
 *  <pre><!--code-[-->
 *  File       csvfile = new File( "mydata.csv" );
 *  CsvManager csvman  = new CsvManager();
 *  CsvSaver   saver   = csvman.makeSaver( csvfile );
 *
 *  ArrayList data = new ArrayList();
 *  data.add( new String[] {"1","a","AA"} );
 *  data.add( new String[] {"2","b","BB"} );
 *  
 *  saver.begin();
 *  for( Iterator lineI = data.iterator(); lineI.hasNext(); ) {
 *    String[] fields = (String[]) lineI.next();
 *    saver.next( fields );
 *  }
 *  saver.end();
 *  <!--code-]--></pre>
 *    <p>Because only one line is saved at a time, 
 *  you can use <code>CsvSaver</code> to save really big CSV files without running out of memory.</p>
 *    <p>Why does <code>CsvSaver</code> have {@link #begin} and {@link #end} methods and why do you need to call them? 
 *  Good question! Unlike the other ways of saving CSV data provided by <i>CSV Manager</i>, when you use
 *  a <code>CsvSaver</code>, <i>you</i> control the saving process. That means you control how often a new data line
 *  is saved to the CSV file. And you control when the saving process begins and ends. You can begin the
 *  saving process sometime after you actually create the <code>CsvSaver</code>, and you can end it at any time, without having
 *  to save all your data.</p>
 *    <p>If you also want to load CSV data one line at a time, check out the {@link CsvLoader} class, 
 *  which works in pretty much the same way as <code>CsvSaver</code>. </p>
 *    <p>The <b><a href="CsvSaver.java.html">Source Code</a></b> of this Java class 
 *    is available under a <a href="http://www.opensource.org/licenses/bsd-license.php">BSD-style license</a>.</p>
 *
 *  @since 1.2.1
 *  @see CsvLoader
 *  @see LineProvider
 *  @see CsvManager#save(Object,List)
 */
public interface CsvSaver {

  /** Tell the <code>CsvSaver</code> you want to begin the saving process. 
   *    <p>This is where the CSV file output stream is opened for reading.</p>
   */
  public void begin();

  
  /** Supply the next line of data as a <code>String[]</code> array.
   *    <p><code>CsvSaver</code> always expects to get data as a <code>String[]</code> array.
   *  If your data is in another format, you will have to convert the data yourself.</p> 
   *    <p>The number of elements in the <code>String[]</code> array determines the number of data fields in the
   *  output CSV data line. If any of the elements are <code>null</code>, 
   *  than an empty <code>String</code> will be written. Note that if the 
   *  {@link CsvSpec#setNumFields CsvSpec.setNumFields} setting is used, then empty fields will be output to make
   *  up for missing elements in the <code>String[]</code> array. <code>setNumFields</code> ensures that
   *  the output CSV data lines always have a minimum number of fields, even if they are empty.</p>
   *    <p><b>Error Handling:</b> when an error occurs, this method always throws a {@link CsvManagerException}.
   *  The details of the bad line are available via the 
   *  {@link CsvManagerException#getBadLine CsvManagerException.getBadLine} method. An exception is also thrown
   *  even if {@link CsvSpec#setIgnoreBadLines CsvSpec.setIgnoreBadLines} is set to <code>true</code>. However in
   *  this case you can continue to call <code>next</code> to get the remaining good lines and you
   *  are not required to stop processing.</p>
   */
  public void next( String[] pLine );

  
  /** Tell the <code>CsvSaver</code> you want to end the saving process.
   *    <p>This is where the CSV file output stream is closed.</p>
   */
  public void end();
}