com.ricebridge.xmlman
Class BadRecord

java.lang.Object
  com.ricebridge.xmlman.BadRecord

public class BadRecord

extends Object

Describes a bad data record that failed for some reason.

Data records fail when the RecordListener processing them returns a BadRecord or throws an Exception. Either the actual data in the data fields was incorrect in some way, or the processing of the data record in a custom RecordListener failed due to database errors or similar problems.

Since XML does not allow recovery from syntax errors, a BadRecord does not describe an XML syntax error, and no BadRecord object is created when an XML syntax error occurs. Instead, an XmlManagerException is always thrown, and processing halts. Note that the endProcess methods of any RecordListeners or RecordProviders are still called when this happens, so that you can exit cleanly.

When a RecordListener encounters a problem with a data record, it can choose to return a BadRecord object to XML Manager from the handleRecord method. This BadRecord is stored for later examination and you can access it using the XmlManager.getBadRecords() method. Normally, only one BadRecord is available, as the default value for the setting XmlSpec.setIgnoreBadRecords is false. If you set this setting to true, then processing will continue despite errors in RecordListeners, and you can then examine all BadRecords that occurred using the getBadRecords method.

When an error occurs in a custom RecordListener that you have written, you have two options; 1. you can create a BadRecord object yourself, with all the details you consider relevant, and return it, or 2. you can just throw an Exception, and let XML Manager create a default BadRecord for you. When option for option 1, you would normally create a BadRecord of SEMANTIC type, using the convenience constructor BadRecord(long,String[],Exception) (The pRecordNumber and pRecord parameters can be obtained from the arguments to the handleRecord method). For option 2, it is much easier (and recommended) to use the support classes such as RecordListenerSupport, as these handle checked Exceptions automatically.

You can also subclass BadRecord to provide additional functionality for your own applications.

The Source Code of this Java class is available under a BSD-style license.

Field Summary

protected Object	iContext A context object describing the error, usually the Exception that caused it.
protected String	iMessage A technical error message.
protected String[]	iRecord The data record that caused the error, if available.
protected long	iRecordNumber The number of the record that caused the error (this number is specific to each RecordSpec).
protected String	iTag An identification tag for the BadRecord origin, usually the record XPath expression, if available.
protected int	iType The type of error that created the BadRecord; UNKNOWN, SEMANTIC, UNEXPECTED.
static int	SEMANTIC Indicate that the bad record was returned by the RecordListener (usually in response to invalid data).
protected static String[]	sTypeNames String names for the type of BadRecord.
static int	UNEXPECTED Indicate that the bad record occurred because an Exception was thrown in the RecordListener.
static int	UNKNOWN Indicate that the bad record has an unknown origin.

Constructor Summary

BadRecord()
Create an empty BadRecord with no information content.

BadRecord(long pRecordNumber, String[] pRecord, Exception pException)
Create a BadRecord based on an Exception.

BadRecord(long pRecordNumber, String[] pRecord, String pMessage)
Create a BadRecord with a specific error message.

BadRecord(String pTag, long pRecordNumber, String[] pRecord, String pMessage)
Create a BadRecord with a specific error message and indicate the record XPath using the pTag parameter.

BadRecord(String pTag, long pRecordNumber, String[] pRecord, String pMessage, int pType)
Create a BadRecord with a specific error message and type, and indicate the record XPath using the pTag parameter.

BadRecord(String pTag, long pRecordNumber, String[] pRecord, String pMessage, Object pContext)
Create a BadRecord with a specific error message and context, and indicate the record XPath using the pTag parameter.

BadRecord(String pTag, long pRecordNumber, String[] pRecord, String pMessage, Object pContext, int pType)
Create a fully described BadRecord object.

Method Summary

Object	getContext() Get the context in which the data record failed.
String	getMessage() Get the technical error message associated with this failed record.
String[]	getRecord() Get the record data fields of the record that failed.
long	getRecordNumber() Get the record number of the failed record.
String	getTag() Get the origin identification tag, usually the record XPath expression.
int	getType() Get the type of bad record that occurred.
String	toString() Return a textual description of the BadRecord suitable for debugging purposes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNKNOWN

public static final int UNKNOWN

Indicate that the bad record has an unknown origin.

See Also:

Constant Field Values

SEMANTIC

public static final int SEMANTIC

Indicate that the bad record was returned by the RecordListener (usually in response to invalid data).

See Also:

Constant Field Values

UNEXPECTED

public static final int UNEXPECTED

Indicate that the bad record occurred because an Exception was thrown in the RecordListener.

See Also:

Constant Field Values

sTypeNames

protected static final String[] sTypeNames

String names for the type of BadRecord.

iTag

protected String iTag

An identification tag for the BadRecord origin, usually the record XPath expression, if available.

iRecordNumber

protected long iRecordNumber

The number of the record that caused the error (this number is specific to each RecordSpec).

iRecord

protected String[] iRecord

The data record that caused the error, if available.

iMessage

protected String iMessage

A technical error message.

iContext

protected Object iContext

A context object describing the error, usually the Exception that caused it.

iType

protected int iType

The type of error that created the BadRecord; UNKNOWN, SEMANTIC, UNEXPECTED.

Constructor Detail

BadRecord

public BadRecord()

Create an empty BadRecord with no information content.

BadRecord

public BadRecord(long pRecordNumber,
                 String[] pRecord,
                 Exception pException)

Create a BadRecord based on an Exception.

Parameters:

pRecordNumber - number of the record that caused the error (counted per RecordSpec)

pRecord - record data (may be partial)

pException - Exception that caused the error

BadRecord

public BadRecord(long pRecordNumber,
                 String[] pRecord,
                 String pMessage)

Create a BadRecord with a specific error message.

Parameters:

pRecordNumber - number of the record that caused the error (counted per RecordSpec)

pRecord - record data (may be partial)

pMessage - technical message describing the error

BadRecord

public BadRecord(String pTag,
                 long pRecordNumber,
                 String[] pRecord,
                 String pMessage)

Create a BadRecord with a specific error message and indicate the record XPath using the pTag parameter.

Parameters:

pTag - indentify the origin of the BadRecord, usually the XPath record expression

pRecordNumber - number of the record that caused the error (counted per RecordSpec)

pRecord - record data (may be partial)

pMessage - technical message describing the error

BadRecord

public BadRecord(String pTag,
                 long pRecordNumber,
                 String[] pRecord,
                 String pMessage,
                 int pType)

Create a BadRecord with a specific error message and type, and indicate the record XPath using the pTag parameter.

Parameters:

pTag - indentify the origin of the BadRecord, usually the XPath record expression

pRecordNumber - number of the record that caused the error (counted per RecordSpec)

pRecord - record data (may be partial)

pMessage - technical message describing the error

pType - type of BadRecord: SEMANTIC, UNEXPECTED, UNKNOWN

BadRecord

public BadRecord(String pTag,
                 long pRecordNumber,
                 String[] pRecord,
                 String pMessage,
                 Object pContext)

Create a BadRecord with a specific error message and context, and indicate the record XPath using the pTag parameter.

Parameters:

pTag - indentify the origin of the BadRecord, usually the XPath record expression

pRecordNumber - number of the record that caused the error (counted per RecordSpec)

pRecord - record data (may be partial)

pMessage - technical message describing the error

pContext - context of the error, usually an Exception, can be null

BadRecord

public BadRecord(String pTag,
                 long pRecordNumber,
                 String[] pRecord,
                 String pMessage,
                 Object pContext,
                 int pType)

Create a fully described BadRecord object.

Parameters:

pTag - indentify the origin of the BadRecord, usually the XPath record expression

pRecordNumber - number of the record that caused the error (counted per RecordSpec)

pRecord - record data (may be partial)

pMessage - technical message describing the error

pContext - context of the error, usually an Exception, can be null

pType - type of BadRecord: SEMANTIC, UNEXPECTED, UNKNOWN

Method Detail

getTag

public String getTag()

Get the origin identification tag, usually the record XPath expression.

getRecordNumber

public long getRecordNumber()

Get the record number of the failed record.

The record number is a counter specific to each RecordSpec. If you are using more than one RecordSpec and you need a global counter, you will need to implement one in a custom RecordListener.

getRecord

public String[] getRecord()

Get the record data fields of the record that failed.

Note: this String[] array may only contain partial data and may also contain nulls.

getMessage

public String getMessage()

Get the technical error message associated with this failed record.

This message is intended for debugging purposes and is not normally intended for users.

getContext

public Object getContext()

Get the context in which the data record failed.

This can be any object that describes the error condition, but is normally the Exception that caused the processing of this data record to fail.

getType

public int getType()

Get the type of bad record that occurred.

The current error types are SEMANTIC, for invalid data values, and UNEXPECTED, for unexpected exceptions thrown by the RecordListener (correctly functioning RecordListeners are expected to return a BadRecord object instead of throwing an Exception).

toString

public String toString()

Return a textual description of the BadRecord suitable for debugging purposes.