/* 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; /** DEPRECATED — DO NOT USE. * <p><b>This interface is included for backwards compatibility only and will be removed in CSV Manager 2.x</b></p> * <p>Implement this interface by extending {@link FieldListenerSupport} to receive each data field as it is loaded.</p> * <p>It is possible to handle each data field separately with this callback interface. * Pass an instance of <code>FieldListener</code> to {@link CsvManager#setFieldListener} and the <code>CsvManager</code> * will call the {@link #addField} method each time a data field is loaded. The String value of each data field is passed to * the <code>FieldListener</code> using {@link #addField}. * At the end of each data line, the {@link #endLine} method is called. When a badly formatted line is * encountered, the {@link #badLine} method is called. Note that a {@link LineListener} object is always used as * part of the CSV loading process, so {@link LineListener#handleBadLine} will <i>also</i> be called. * During loading, <code>FieldListener</code> methods are always called <i>before</i> {@link LineListener} methods.</p> * <p>If you set {@link CsvManager#setIgnoreBadLines} to <code>true</code> then loading of CSV data will continue * past any badly formatted data lines. If this setting is <code>false</code> (the default), then loading is halted * and a {@link CsvManagerException} <code>(CODE_bad_line)</code> is thrown <i>after</i> <code>badLine</code> is called.</p> * <p>To use a <code>FieldListener</code>, just use the {@link CsvManager#load CsvManager.load*} methods in the usual manner. * The <code>FieldListener</code> functionality is independent of the main loading functionality which uses {@link LineListener}.</p> * <p>An example of a <code>FieldListener</code> is provided by {@link DebugFieldListener}. This is a simple <code>FieldListener</code> * implementation that prints out debugging information as each data field is parsed. You can use it to see exactly how * far into your CSV file the parser gets before failing.</p> * <p><b>Important:</b> You should implement this interface by extending the helper class {@link FieldListenerSupport}. * This helper class adds fault tolerance and helps make your <code>FieldListener</code> * implementation compatible with any future changes to the CSV Manager API.</p> * <p>Note: you may assume in your implementation that no parameters are <code>null</code>.</p> * <p>The <b><a href="FieldListener.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> * * @see FieldListenerSupport * @see CsvManager * @see CsvManagerException * @deprecated */ public interface FieldListener { /** Called just before loading of the CSV data starts. * <p>You should use this method to initialise any data containers in your <code>FieldListener</code>.</p> * <p>This method is called before {@link LineListener#startProcess}.</p> * @see #endLoad */ public void startLoad(); /** Called just after loading of the CSV data ends. * <p>You should use this method to release any resources used by your <code>FieldListener</code>.</p> * <p>This method is called before {@link LineListener#endProcess}.</p> * @see #startLoad */ public void endLoad(); /** Called each time a data field is loaded. * The String value of the data field is provided. * <p>This method is called before {@link LineListener#handleLine}.</p> * <p>Note: implement this method by implementing {@link FieldListenerSupport#addFieldImpl}.</p> * @param pValue String value of data field */ public void addField( String pValue ); /** Called each time the end of a data line is reached. * <p>If you encounter any errors in the data fields for the current line, use this method to * report them by returning a {@link BadLine} object describing the error (If you also return a {@link BadLine} from * a {@link FieldListener} from the same line, the error message from the <code>BadLine</code> returned here will be appended * to the <code>FieldListener</code> <code>BadLine</code> error message. This is to ensure that only one * <code>BadLine</code> object is created per bad line). * If the data is valid, then return <code>null</code> to indicate that everything is OK.</p> * <p>Note: this method is called before {@link LineListener#handleLine}.</p> * <p>Note: implement this method by implementing {@link FieldListenerSupport#endLineImpl}.</p> * @param pLineNumber line number index, counting from 1 * @param pOriginalLine original line of data * @return <code>null</code> if line is OK, {@link BadLine} object if line was bad in some way */ public BadLine endLine( String pOriginalLine, long pLineNumber ); /** Called when a badly formatted data line is encountered. * <p>This method is only called once if {@link CsvManager#setIgnoreBadLines} is <code>true</code>. * See {@link LineListener#handleBadLine} for more details about the <code>pBadLine</code> parameter. * If you return a {@link BadLine} from {@link #endLine}, then it is <i>not</i> subsequently passed into this * method. Only {@link BadLine}s generated externally are passed into the <code>FieldListener</code>.</p> * <p>This method is called before {@link LineListener#handleBadLine}.</p> * <p>Note: implement this method by implementing {@link FieldListenerSupport#badLineImpl}.</p> * @param pBadLine {@link BadLine} object describing problem * @see LineListener#handleBadLine */ public void badLine( BadLine pBadLine ); }