/* Copyright (c) 2003-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; /** Use this interface to create custom CSV data savers. * <p>This callback interface allows you to provide data lines on demand so that they can be saved as * quickly as possible with minimal memory usage. This means that you can avoid storing all the data you want to * save in memory at the same time. For example, if you want to save data from a database to a CSV file, you do not * have to load all the data at once. Instead you can step through the {@link java.sql.ResultSet} and save each line directly. * See the <a href="../../../../examples/database/README.htm">database example</a> * for more information.</p> * <p>To implement this interface, please extend {@link CustomLineProvider}, as that will help keep your code * compatible with future versions. To use a <code>LineProvider</code>, call the {@link CsvManager#save(Object, LineProvider)} or * {@link CsvManager#save(Object, LineSpec, LineProvider)} methods.</p> * <p>When you pass an instance of <code>LineProvider</code> to {@link CsvManager}, it will * call the {@link #hasNextLine hasNextLine} and {@link #nextLine nextLine} methods to get each data line to save. * You then provide the data line as a <code>String[]</code> array.</p> * <p>As <code>CsvManager</code> saves the data, it calls the * methods of the <code>LineProvider</code> in a defined sequence:</p> * <ol><li>{@link #setCsvSpec setCsvSpec}</li> * <li>{@link #setLineSpec setLineSpec}</li> * <li>{@link #startProcess startProcess}</li> * <li>{@link #hasNextLine hasNextLine}</li> * <li>{@link #nextLine nextLine}</li> * <li>{@link #endProcess endProcess}</li></ol> * <p>The {@link #hasNextLine hasNextLine} and {@link #nextLine nextLine} methods are called * called repeatedly, once for each data line.</p> * <p>When writing your own <code>LineProvider</code>, the easiest way to get started is to review the source code for the * existing <code>LineProviders</code> used by <code>CsvManager</code>. <code>CsvManager</code> uses <code>LineProviders</code> * internally for all data saving operations. * The {@link BasicLineProvider} is a very simple example and a good place to start.</p> * Here is the full list of standard <code>LineProviders</code>:</p> * <ul><li>{@link BasicLineProvider}</li> * <li>{@link AsListsLineProvider}</li> * <li>{@link TableModelLineProvider}</li> * <li>{@link ResultSetLineProvider}</li> * <li>{@link BeanLineProvider}</li></ul> * <p>Note: you may assume in your implementation that no parameters are <code>null</code>.</p> * <p><b>Error Handling</b><br /> * If an error occurs when you are creating the data for the next line, * you can allow <code>Exceptions</code> to pass up to the <code>CustomLineProvider</code> class, without handling them yourself. * In this case <code>CsvManager</code> will handle them for you, either * halting the save operation, or creating a <code>BadLine</code> and storing it, depending on the value of the * {@link CsvSpec#setIgnoreBadLines} setting.</p> * <p><b>Important</b><br /> * In order to ensure the greatest compatibility with future releases and to take advantage of additional error handling * functionality, please implement your <code>LineProvider</code> by extending the abstract {@link CustomLineProvider} class. * This class ensures that all data you receive is well-formed (no <code>nulls</code>), and also creates standard * exceptions when problems do occur.</p> * <p>Compatibility Note: <i>CSV Manager 1.1</i> used {@link LineProviderSupport} * instead of <code>CustomLineProvider</code>. Existing code will still work with this base class, but you should * always use <code>CustomLineProvider</code> for new code.</p> * <p>The <b><a href="LineProvider.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> */ public interface LineProvider { // public methods /** Set the current {@link CsvSpec} settings. * <p>You can implement this method to get the values of the current settings, * and use them to modify your data handling. For example, {@link TableModelLineProvider} * uses the custom property <code>TableModel.saveHeaders</code> to output the headers of the * {@link javax.swing.table.TableModel TableModel} that it is saving as the first data line. * You can easily use your own * custom properties by calling the {@link CsvSpec#setProperty CsvSpec.setProperty} and * {@link CsvSpec#getProperty CsvSpec.getProperty} methods.</p> * <p>Note: to actually set the {@link CsvSpec} object, you use {@link CsvManager#setCsvSpec CsvManager.setCsvSpec}.</p> * <p><b>Implement by overriding {@link CustomLineProvider#setCsvSpecImpl CustomLineProvider.setCsvSpecImpl}.</b></p> * @param pCsvSpec <code>CsvSpec</code> object */ public void setCsvSpec( CsvSpec pCsvSpec ); /** Set the current {@link LineSpec} field specification settings. * <p>You can implement this method to get the list of field names that * apply to the data. This is useful when you need to identify the data fields * for additional functionality. For example, the {@link BeanLineProvider} class uses the field * names to determine the correct <i>get</i> methods to call.</p> * <p>You can add your own metadata for use by {@link CustomLineProvider CustomLineProviders} * by subclassing <code>LineSpec</code> and adding appropriate methods to return your custom metadata.</p> * <p><b>Implement by overriding {@link CustomLineProvider#setLineSpecImpl CustomLineProvider.setLineSpecImpl}.</b></p> * @param pLineSpec field specification */ public void setLineSpec( LineSpec pLineSpec ); /** Called just before saving of the CSV data starts. * <p>You should use this method to initialise any data sources in your <code>LineProvider</code>. * For example, you can initialise any database connections or other resources that you need to use to process the data.</p> * <p><b>Implement by overriding {@link CustomLineProvider#startProcessImpl CustomLineProvider.startProcessImpl}.</b></p> */ public void startProcess(); /** Indicate that another data line is available to save. * <p>Each data line is converted into CSV by first calling this method to check that * another data line is available, and then calling {@link #nextLine} to get the actual data. * Once this method returns <code>false</code>, processing finishes.</p> * <p>You use this method to control the saving process. Keep returning <code>true</code> as long as * you have more data lines to save.</p> * <p><b>Implement by overriding {@link CustomLineProvider#hasNextLineImpl CustomLineProvider.hasNextLineImpl}.</b></p> */ public boolean hasNextLine(); /** Provide each data line as a <code>String[]</code> array for the CSV output. * <p>This is the most important method of the <code>LineProvider</code> interface. This is where you * actually provide your data to <i>CSV Manager</i>. The data is provided as a <code>String[]</code> array of field values. * Any <code>null</code> fields are set to empty strings, and any missing fields are also set to empty strings (when using * {@link CsvSpec#setNumFields CsvSpec.setNumFields}. * <p><b>Implement by overriding {@link CustomLineProvider#nextLineImpl CustomLineProvider.nextLineImpl}.</b></p> */ public String[] nextLine(); /** Indicate the end of the saving process. * <p>This method is called once the CSV output has been fully completed. You can use it to * release any resources such as database connections that you were using to create the data.</p> * <p><b>Implement by overriding {@link CustomLineProvider#endProcessImpl CustomLineProvider.endProcessImpl}.</b></p> */ public void endProcess(); }