/* Copyright (c) 2005 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.xmlman; import java.util.*; /** Implement this interface by extending {@link BadRecordListenerSupport} to receive a {@link BadRecord} object * for each failed data record. * <p>This callback interface allows you to handle failed data records as soon as they occur. The most common * use-case is to log them for debugging purposes.</p> * <p>Once you have created your own <code>BadRecordListener</code>, you can use it by calling the * {@link XmlManager#setBadRecordListener setBadRecordListener} method of {@link XmlManager} before starting the * the load or save process (<code>BadRecordListener</code> receives failed data records from both load and save processes).</p> * <p>The {@link XmlManager#getBadRecords getBadRecords} method of <code>XmlManager</code> is implemented by using the * {@link StandardBadRecordListener} class, which you should review if you are going to write your own * <code>BadRecordListener</code>. * <p>When using your own <code>BadRecordListener</code> you should probably set the * {@link XmlSpec#setIgnoreBadRecords setIgnoreBadRecords} setting to * <code>true</code>, so that you receive all the failed data records.</p> * <p><b>Calling Sequence</b><br /> * When used with a {@link RecordListener} or a {@link RecordProvider}, the following method calling sequence is followed:</p> * <ol><li>{@link RecordListener#startProcess RecordListener.startProcess} OR * {@link RecordProvider#startProcess RecordProvider.startProcess}</li> * <li>{@link #startProcess BadRecordListener.startProcess}</li> * <li>{@link RecordListener#handleRecord RecordListener.handleRecord} OR * {@link RecordProvider#hasNextRecord RecordProvider.hasNextRecord}, * {@link RecordProvider#nextRecord RecordProvider.nextRecord}</li> * <li>{@link #handleBadRecord BadRecordListener.handleBadRecord}</li> * <li>{@link #endProcess BadRecordListener.endProcess}</li> * <li>{@link RecordListener#endProcess RecordListener.endProcess} OR * {@link RecordProvider#endProcess RecordProvider.endProcess}</li></ol> * <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>RecordListener</code> by extending the abstract {@link BadRecordListenerSupport} 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>In fact, you should probably extend the abstract {@link CollectingBadRecordListener} class, to ensure that the * <code>getBadRecords</code> method continues to function correctly. * <p>The <b><a href="BadRecordListener.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 BadRecordListener { // public methods /** Indicate the start of the loading or saving process. * <p>This method is called <i>after</i> the {@link RecordListener#startProcess} and {@link RecordProvider#startProcess} methods. * You can initialise any logging facilities or other resources that you need to use to process the failed data records.</p> */ public void startProcess(); /** Handle a failed data record. * <p>As soon as XML Manager detects a failed data record, this method is called so that * you can log the problem,or deal with it in another manner.</p> * @param pBadRecord {@link BadRecord} object describing the error */ public void handleBadRecord( BadRecord pBadRecord ); /** Indicate the end of the loading or saving process. * <p>This method is called <i>before</i> the {@link RecordListener#endProcess} * and {@link RecordProvider#endProcess} methods. You can use it to * release any resources that you were using to handle the failed data records.</p> * <p>Note: this method <i>will</i> be called even if other errors occur, * so long as the call to {@link #startProcess} returned normally. * If your <code>startProcess</code> method does critical things, make sure that it fails cleanly.</p> */ public void endProcess(); }