org.openadaptor.dostrings
Class DOStringReader

java.lang.Object
  org.openadaptor.dostrings.DOStringReaderWriter
      org.openadaptor.dostrings.DOStringReader

Direct Known Subclasses:

DelimitedStringReader, DOStreamReader, FixedWidthStringReader, SingleStringReader

public abstract class DOStringReader
extends DOStringReaderWriter

Abstract base class for transforming strings into DataObjects. Can be initialised with the following properties.

 DateFormat          Allows user to specify a date, you can use
                         YY or YYYY  eg: 01 or 2001
                         MM or MMMM  eg: 10 or Oct
                         DD          eg:  2
                         TZN         eg: GMT
                         hh          eg: 10
                         mm          eg: 30
                         ss          eg: 05
                         NN          eg: AM or PM
 EmptyStringAsNull   If true then empty string String values will be translated
                     to null values
 NullString          Occurences of this string will be translated to null
                     values
 AttTrimN            Trim the Nth attribute value
 

When reading multiple types in using the reader, a specific field must be nominated as containing a distinguishing string for that record. The field can either be the same for each DOType (the first field for example) or a different field can be defined for each DOType. If the field number is different, it is important to note that each record will be checked against each type matching string in turn, i.e. Type1 first, then Type2 if it is not of type 1, then Type3 etc. For best performance, The most common record types should be the first checked; if you have 800 Type A records, and only 100 Type B and Type C, then make Type A "Type1" in the properties file.

The property required is the "TypeFieldNumber", and can be defined at the component level, for all the DOTypes:

 A.Cn.TypeFieldNumber = 1
 A.Cn.Type1           = aType
 A.Cn.Type2           = bType
 

or at the DOType level if different fields distinguish different types:

 A.Cn.Type1                 = aType
 A.Cn.aType.TypeFieldNumber = 1
 A.Cn.Type2                 = bType
 A.Cn.bType.TypeFieldNumber = 2
 

The value matched in the type field can be a DOType attribute (very unlikely unless your DataObjects are not SimpleDataObjects), but is more often the DOType name, or a constant string. The value is defined in the "TypeFieldMatch" property. If the value is a constant string, then it must be enclosed in quotes. If it is the DOType name, the special property value '-typeName-' must be used, or if it is an attribute value, just the attribute name:

 A.Cn.aType.TypeFieldMatch = "TYPE_A"
 A.Cn.aType.TypeFieldMatch = -typeName-
 A.Cn.aType.TypeFieldMatch = typeId
 

Note that you may also define the property "AttNameN" where N is the type field number, to define what happens to the contents of the field that was used for the type matching. The value of the property can either be an attribute name, in which case the field value will be stored in that (String) attribute, or it can be "-ignore-" in which case the field value is discarded.

 A.Cn.aType.TypeFieldNumber = 3
 A.Cn.aType.TypeFieldMatch  = "TYPE_A"
 A.Cn.aType.AttName3        = -ignore-   ;; field is discarded
 A.Cn.aType.AttName3        = TypeID     ;; TYPE_A stored in TypeID attr
 

Refer to the base class DOStringReaderWriter for other base properties.

When trying to convert the String into a DataObject, the component will try to match the DOTypes defined in the properties file with any type declarations in the string itself. By default this matching is case sensitive. You can override this by setting:

 A.Cn.CaseSensitiveTypeMatching = false
 

Author:

Fred Perry, Tim Bissell, Russ Fennell

See Also:

DOStringReaderWriter

Nested Class Summary

Nested classes/interfaces inherited from class org.openadaptor.dostrings.DOStringReaderWriter

DOStringReaderWriter.TypeInfo

Field Summary

protected boolean	_case_sensitive_types flag to indicate that DOType matching should be case sensitive
protected DateFormatter	_date_formatter a DateFormatter to parse the date strings
protected boolean	_empty_string_as_null Deprecated. Use isTreatEmptyStringAsNull() instead - this is going private in 1.7.5
protected java.lang.String[]	_last_chop Contains last string array produced by chop() in getDOTypeForRecord.
protected java.lang.String	_null_string Deprecated. Use getNullString() instead - this is going private in 1.7.5
protected java.util.Hashtable	_trim_flag_arrays Hashtable of DataObject attribute trim flags keyed on type name, the order of the array is based on order of specification
(package private) static org.apache.log4j.Logger	log
protected static java.lang.String	TRIM_PROP

Fields inherited from class org.openadaptor.dostrings.DOStringReaderWriter

_numFields, _numFieldsAtt, _single_type_property_defined, _textEncoding, _type, _type_field_number, _typeInfo_array, _typeInfo_count, _typeInfos, ACT_ATTR, ACT_IGNORE, ACT_STRING, ACT_TYPENAME, DEFAULT_ATT_STRING, DEFAULT_TYPE_STRING, KW_IGNORE, KW_TYPENAME

Constructor Summary

DOStringReader()

Method Summary

abstract java.lang.String[]	chop(java.lang.String record, java.lang.String type_name) Implement this method to extract attribute value strings from the record string.
java.lang.String	chopField(java.lang.String record, java.lang.String type_name, int field_num) Implement this method to make matching against multiple types more efficient.
DataObject	createDataObjectForRecord(java.lang.String record) Returns a SimpleDataObject with a DOType suitable for the supplied record.
DataObject	fromString(java.lang.String s) Convert a string (record) to a DataObject
DOType	getDOTypeForRecord(java.lang.String record) Searches DOTypes for the one which matches the string record.
java.lang.String	getNullString()
void	init(java.util.Properties props, java.lang.String prefix) Initialise from properties object.
boolean	isTreatEmptyStringAsNull() If true, then subclasses should treat empty (String) fields as containing null rather than as zero-length strings.
void	setNullString(java.lang.String s) Set the value of the string which should be interpreted as (replaced by) null.
void	setTreatEmptyStringAsNull(boolean flag) Sets indicator as to whether empty fields should be returned as nulls or as empty (zero length) strings.

Methods inherited from class org.openadaptor.dostrings.DOStringReaderWriter

getNumFields, getNumFieldsAtt, getTextEncoding, init, init, requireAttNameOrNumAttributes, setNumFields, setNumFieldsAtt, useDataObjectAttributes

Methods inherited from class java.lang.Object

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

Field Detail

log

static org.apache.log4j.Logger log

TRIM_PROP

protected static final java.lang.String TRIM_PROP

See Also:

Constant Field Values

_empty_string_as_null

protected boolean _empty_string_as_null

Deprecated. Use isTreatEmptyStringAsNull() instead - this is going private in 1.7.5

Flag that creates null values for empty strings

_null_string

protected java.lang.String _null_string

Deprecated. Use getNullString() instead - this is going private in 1.7.5

String used in file to represent null string

_trim_flag_arrays

protected java.util.Hashtable _trim_flag_arrays

Hashtable of DataObject attribute trim flags keyed on type name, the order of the array is based on order of specification

_date_formatter

protected DateFormatter _date_formatter

a DateFormatter to parse the date strings

_case_sensitive_types

protected boolean _case_sensitive_types

flag to indicate that DOType matching should be case sensitive

_last_chop

protected java.lang.String[] _last_chop

Contains last string array produced by chop() in getDOTypeForRecord. Can be used in fromString().

Constructor Detail

DOStringReader

public DOStringReader()

Method Detail

init

public void init(java.util.Properties props,
                 java.lang.String prefix)
          throws DOStringException

Initialise from properties object. See class comment for property values

Overrides:

init in class DOStringReaderWriter

Parameters:

props - Properties object

prefix - Prefix string to search for properties

Throws:

DOStringException - Thrown if initialisation fails, mandatory properties are missing or properties cannot be parsed.

fromString

public DataObject fromString(java.lang.String s)
                      throws DOStringException

Convert a string (record) to a DataObject

Parameters:

s - record string

Returns:

a DataObject populated from record string

Throws:

DOStringException

chop

public abstract java.lang.String[] chop(java.lang.String record,
                                        java.lang.String type_name)
                                 throws DOStringException

Implement this method to extract attribute value strings from the record string.

Parameters:

record - The record string

type_name - The type name of the DataObject that will be created from this record. You can use this to access internal hashtables

Returns:

An array of strings that will be used as values to the DataObject

Throws:

DOStringException

chopField

public java.lang.String chopField(java.lang.String record,
                                  java.lang.String type_name,
                                  int field_num)
                           throws DOStringException

Implement this method to make matching against multiple types more efficient. It will be used to extract the type field value for comparison with the TypeFieldMatch value. You do not need to implement it, but if you do, it may speed up the record reading process.

Parameters:

record - The record string.

type_name - The type name of the DataObject that will be created from this record. You can use this to access internal hashtables.

field_num - The index (1..n) of the field to be returned. starts at one)

Returns:

Null (overridden to return contents of field field_num as a String.

Throws:

DOStringException

getDOTypeForRecord

public DOType getDOTypeForRecord(java.lang.String record)
                          throws DOStringException

Searches DOTypes for the one which matches the string record. Loops over the DOTypes in order, and returns the first one whose TypeFieldMatch succeeds on 'record'. As a primitive optimisation, if it uses 'chop' to get the TypeField, then the results of the last chop are stored in last_chop for fromString() to use, so it does not need to chop the matched record twice (once to match, once to

Parameters:

record - String record for which DOType is required

Returns:

DOType corresponding to record.

Throws:

DOStringException - If no DOType matches record.

createDataObjectForRecord

public DataObject createDataObjectForRecord(java.lang.String record)
                                     throws DOStringException

Returns a SimpleDataObject with a DOType suitable for the supplied record. This calls getDOTypeForRecord(record), and returns a SimpleDataObject of the returned DOType. Override this if you want to return objects other than SimpleDataObjects.

Parameters:

record - The record string

Returns:

An empty SimpleDataObject of the type to be populated.

Throws:

DOStringException

setTreatEmptyStringAsNull

public void setTreatEmptyStringAsNull(boolean flag)

Sets indicator as to whether empty fields should be returned as nulls or as empty (zero length) strings.

Parameters:

flag - If true all empty fields are returned as nulls, otherwise as zero-length strings.

isTreatEmptyStringAsNull

public boolean isTreatEmptyStringAsNull()

If true, then subclasses should treat empty (String) fields as containing null rather than as zero-length strings.

Returns:

setNullString

public void setNullString(java.lang.String s)

Set the value of the string which should be interpreted as (replaced by) null. Defaults to null. Typically you might have a 'magic' string like NULL to explicitly indicate a null field.

Parameters:

s - new null String.

getNullString

public java.lang.String getNullString()