com.univocity.api.entity.text.fixed
Class FixedWidthEntityConfiguration

java.lang.Object
  extended by com.univocity.api.entity.Configuration
      extended by com.univocity.api.entity.text.TextEntityConfiguration<FixedWidthFormat>
          extended by com.univocity.api.entity.text.fixed.FixedWidthEntityConfiguration

public final class FixedWidthEntityConfiguration
extends TextEntityConfiguration<FixedWidthFormat>

This is the class used to configure fixed-width data entities.

Note the length of all fields is required in order to process fixed-width records.

Author:
uniVocity Software Pty Ltd - dev@univocity.com

Field Summary
 
Fields inherited from class com.univocity.api.entity.text.TextEntityConfiguration
fieldLengths, headers, identifiers
 
Constructor Summary
FixedWidthEntityConfiguration()
           
 
Method Summary
 void addField(int length)
          Adds the length of the next field in a fixed-width record.
 void copyDefaultsFrom(Configuration defaultConfig)
          Applies default values to undefined settings using a Configuration object.
 int[] getFieldLengths()
          Returns the sequence of lengths for each field that form a fixed-width record.
 int getFieldsPerRecord()
          Returns the number of fields in each record of a fixed-width data entity.
 F getFormat()
          Returns the input/output format settings for a given text.
 boolean getIgnoreLeadingWhitespaces()
          Determines whether to remove leading white spaces from values being read/written
 boolean getIgnoreTrailingWhitespaces()
          Determines whether to remove trailing white spaces from values being read/written
 int getInputBufferSize()
          Defines the number of characters held by the entity buffer when reading from the input
 int getMaxCharsPerColumn()
          Returns the maximum number of characters allowed for any given value being written/read.
 int getMaxColumns()
          Returns the hard limit on how many columns a record can have.
 String getNullValue()
          Returns the default value used in substitution of null when there are empty fields in a text record.
 boolean getReadInputOnSeparateThread()
          Defines whether or not a separate thread will be used to read characters from the input while parsing.
 boolean getRecordEndsOnNewline()
          Indicates whether or not a record is considered parsed when a newline is reached.
 boolean getSkipEmptyLines()
          Determines whether to skip empty lines of text when reading: if the entity reads an empty line from the input, it will be discarded. when writing: if the entity receives an empty or null row to write to the output, it will be ignored. defaults to true.
 boolean getSkipTrailingCharsUntilNewline()
          Indicates whether or not any trailing characters beyond the record's length should be skipped until the newline is reached.
 boolean isHeaderExtractionEnabled()
          Indicates whether or not the first valid record parsed from the input should be used to derive the names of each column of this entity.
 boolean isHeaderWritingEnabled()
          Indicates whether or not to write headers to the output when writing records to an empty entity.
protected  FixedWidthFormat newDefaultFormat()
          Creates a new default FixedWidthFormat instance
 void setFieldLengths(int... fieldLengths)
          Associates a length with each column of records returned by the fixed-width data entity.
 void setFieldsPerRecord(int fieldsPerRecord)
          Defines the number of fields per record.
 void setFormat(F format)
          Defines the input/output format settings for a given text.
 void setHeaderExtractionEnabled(boolean extractHeaders)
          Defines whether or not the first valid record parsed from the input should be used to derive the names of each column of this entity.
 void setHeaderWritingEnabled(boolean headerWritingEnabled)
          Indicates whether or not to write headers to the output when writing records to an empty entity.
 void setIgnoreLeadingWhitespaces(boolean ignoreLeadingWhitespaces)
          Determines whether to remove leading white spaces from values being read/written
 void setIgnoreTrailingWhitespaces(boolean ignoreTrailingWhitespaces)
          Determines whether to remove trailing white spaces from values being read/written
 void setInputBufferSize(int inputBufferSize)
          Defines the number of characters held by the entity buffer when reading from the input
 void setMaxCharsPerColumn(int maxCharsPerColumn)
          Defines the maximum number of characters allowed for any given value being written/read.
 void setMaxColumns(int maxColumns)
          Defines a hard limit on how many columns a record can have.
 void setNullValue(String nullValue)
          Defines a default value to be used in substitution of null when there are empty fields in a text record.
 void setReadInputOnSeparateThread(boolean readInputOnSeparateThread)
          Defines whether or not a separate thread will be used to read characters from the input while parsing.
 void setRecordEndsOnNewline(boolean recordEndsOnNewline)
          Defines whether or not a record is considered parsed when a newline is reached.
 void setSkipEmptyLines(boolean skipEmptyLines)
          Determines whether to skip empty lines of text when reading: if the entity reads an empty line from the input, it will be discarded. when writing: if the entity receives an empty or null row to write to the output, it will be ignored.
 void setSkipTrailingCharsUntilNewline(boolean skipTrailingCharsUntilNewline)
          Defines whether or not any trailing characters beyond the record's length should be skipped until the newline is reached.
 
Methods inherited from class com.univocity.api.entity.text.TextEntityConfiguration
getHeaders, getIdentifiers, getNumberOfRecordsToRead, setFieldsAndLengths, setHeaders, setIdentifiers, setNumberOfRecordsToRead, validateHeaders
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FixedWidthEntityConfiguration

public FixedWidthEntityConfiguration()
Method Detail

setFieldLengths

public final void setFieldLengths(int... fieldLengths)
Associates a length with each column of records returned by the fixed-width data entity. All lengths must be greater than 0.

Overrides:
setFieldLengths in class TextEntityConfiguration<FixedWidthFormat>
Parameters:
fieldLengths - the sequence of lengths for each field that form a fixed-width record.

setFieldsPerRecord

public final void setFieldsPerRecord(int fieldsPerRecord)
Defines the number of fields per record. Lengths must be defined through either addField(int) or setFieldLengths(int...)

Parameters:
fieldsPerRecord - The number of fields in a fixed-width record. It must be greater than 0.

addField

public final void addField(int length)
Adds the length of the next field in a fixed-width record.

Note the total number of fields per record must have been defined using setFieldsPerRecord(int) prior to invoking this method.

This method can be called the same number of times as there are fields per record.

Parameters:
length - the length of the next field. It must be greater than 0.

getFieldsPerRecord

public final int getFieldsPerRecord()
Returns the number of fields in each record of a fixed-width data entity.

Returns:
the number of fields in each record of a fixed-width data entity

getFieldLengths

public final int[] getFieldLengths()
Returns the sequence of lengths for each field that form a fixed-width record.

An IllegalStateException will be thrown if the field lengths were not fully configured.

Overrides:
getFieldLengths in class TextEntityConfiguration<FixedWidthFormat>
Returns:
the sequence of lengths for each field that form a fixed-width record.

getRecordEndsOnNewline

public final boolean getRecordEndsOnNewline()
Indicates whether or not a record is considered parsed when a newline is reached. Examples:

Defaults to false

Returns:
true if a record should be considered parsed when a newline is reached, otherwise false

setRecordEndsOnNewline

public final void setRecordEndsOnNewline(boolean recordEndsOnNewline)
Defines whether or not a record is considered parsed when a newline is reached. Examples:

Parameters:
recordEndsOnNewline - a flag indicating whether or not a record is considered parsed when a newline is reached

getSkipTrailingCharsUntilNewline

public final boolean getSkipTrailingCharsUntilNewline()
Indicates whether or not any trailing characters beyond the record's length should be skipped until the newline is reached.
For example, if the record length is 5, but the row contains 12345678\n, the portion containing 678\n will be discarded and not considered part of the next record

Defaults to false

Returns:
true if any trailing characters beyond the record's length should be skipped until the newline is reached, otherwise false

setSkipTrailingCharsUntilNewline

public final void setSkipTrailingCharsUntilNewline(boolean skipTrailingCharsUntilNewline)
Defines whether or not any trailing characters beyond the record's length should be skipped until the newline is reached.
For example, if the record length is 5, but the row contains 12345678\n, then portion containing 678\n will be discarded and not considered part of the next record

Parameters:
skipTrailingCharsUntilNewline - a flag indicating if any trailing characters beyond the record's length should be skipped until the newline is reached

copyDefaultsFrom

public final void copyDefaultsFrom(Configuration defaultConfig)
Applies default values to undefined settings using a Configuration object.

Parameters:
defaultConfig - a configuration object from where to obtain default settings.

newDefaultFormat

protected final FixedWidthFormat newDefaultFormat()
Creates a new default FixedWidthFormat instance

Returns:
a new instance of a text format configuration.

getSkipEmptyLines

public final boolean getSkipEmptyLines()
Determines whether to skip empty lines of text defaults to true.

Returns:
a flag indicating whether or not empty lines should be skipped.

setSkipEmptyLines

public final void setSkipEmptyLines(boolean skipEmptyLines)
Determines whether to skip empty lines of text

Parameters:
skipEmptyLines - a flag indicating whether or not empty lines should be skipped.

getIgnoreTrailingWhitespaces

public final boolean getIgnoreTrailingWhitespaces()
Determines whether to remove trailing white spaces from values being read/written

defaults to true.

Returns:
true if trailing white spaces should be removed from values of this entity; false otherwise

setIgnoreTrailingWhitespaces

public final void setIgnoreTrailingWhitespaces(boolean ignoreTrailingWhitespaces)
Determines whether to remove trailing white spaces from values being read/written

Parameters:
ignoreTrailingWhitespaces - flag indicating whether trailing white spaces should be removed from values of this entity.

isHeaderExtractionEnabled

public final boolean isHeaderExtractionEnabled()
Indicates whether or not the first valid record parsed from the input should be used to derive the names of each column of this entity.

defaults to false.

Returns:
true if the first valid record parsed from the input should be used to derive the names of each column, false otherwise

setHeaderExtractionEnabled

public final void setHeaderExtractionEnabled(boolean extractHeaders)
Defines whether or not the first valid record parsed from the input should be used to derive the names of each column of this entity.

Parameters:
extractHeaders - a flag indicating whether the first valid record parsed from the input be used to derive the names of each column of this entity.

getIgnoreLeadingWhitespaces

public final boolean getIgnoreLeadingWhitespaces()
Determines whether to remove leading white spaces from values being read/written

defaults to true.

Returns:
true if leading white spaces should be removed from values of this entity; false otherwise.

setIgnoreLeadingWhitespaces

public final void setIgnoreLeadingWhitespaces(boolean ignoreLeadingWhitespaces)
Determines whether to remove leading white spaces from values being read/written

defaults to true.

Parameters:
ignoreLeadingWhitespaces - true if leading white spaces should be removed from values of this entity.

getInputBufferSize

public final int getInputBufferSize()
Defines the number of characters held by the entity buffer when reading from the input

Defaults to 1024*1024 characters (i.e. 1,048,576 characters).

Returns:
the number of characters held by the entity buffer when reading from the input

setInputBufferSize

public final void setInputBufferSize(int inputBufferSize)
Defines the number of characters held by the entity buffer when reading from the input

Parameters:
inputBufferSize - the new input buffer size (in number of characters)

getReadInputOnSeparateThread

public final boolean getReadInputOnSeparateThread()
Defines whether or not a separate thread will be used to read characters from the input while parsing. Defaults to true if the number of available processors at runtime is greater than 1

Returns:
true if the input should be read on a separate thread, false otherwise

setReadInputOnSeparateThread

public final void setReadInputOnSeparateThread(boolean readInputOnSeparateThread)
Defines whether or not a separate thread will be used to read characters from the input while parsing.

Parameters:
readInputOnSeparateThread - the flag indicating whether or not the input should be read on a separate thread

setNullValue

public final void setNullValue(String nullValue)
Defines a default value to be used in substitution of null when there are empty fields in a text record.

Parameters:
nullValue - a default value used instead of null for reading and writing.

getNullValue

public final String getNullValue()
Returns the default value used in substitution of null when there are empty fields in a text record.

defaults to null.

Returns:
a default value used instead of null for reading and writing.

getMaxCharsPerColumn

public final int getMaxCharsPerColumn()
Returns the maximum number of characters allowed for any given value being written/read.
This is required to avoid getting an OutOfMemoryError in case a file does not have a valid format.
In such cases the entity might just keep reading from the input until its end, or until the memory is exhausted. This provides a limit which avoids unwanted JVM crashes.

defaults to 4096.

Returns:
the maximum number of characters any given field in a record can have

setMaxCharsPerColumn

public final void setMaxCharsPerColumn(int maxCharsPerColumn)
Defines the maximum number of characters allowed for any given value being written/read.
This is required to avoid getting an OutOfMemoryError in case a file does not have a valid format.
In such cases the entity might just keep reading from the input until its end, or until the memory is exhausted. This provides a limit which avoids unwanted JVM crashes.

Parameters:
maxCharsPerColumn - the maximum number of characters any given field in a record can have

getMaxColumns

public final int getMaxColumns()
Returns the hard limit on how many columns a record can have.
This is required to avoid getting an OutOfMemoryError in case a file does not have a valid format.
In such cases the entity might just keep reading from the input until its end, or until the memory is exhausted. This provides a limit which avoids unwanted JVM crashes.

defaults to 512.

Returns:
the maximum number of columns a record can have.

setMaxColumns

public final void setMaxColumns(int maxColumns)
Defines a hard limit on how many columns a record can have.
This is required to avoid getting an OutOfMemoryError in case a file does not have a valid format.
In such cases the entity might just keep reading from the input until its end, or until the memory is exhausted. This provides a limit which avoids unwanted JVM crashes.

Parameters:
maxColumns - the maximum number of columns a record can have.

isHeaderWritingEnabled

public final boolean isHeaderWritingEnabled()
Indicates whether or not to write headers to the output when writing records to an empty entity.

Note: write-only entities (i.e. obtained from WriterProvider) do not provide information about whether the output is empty or not. uniVocity will only attempt to write headers to such entities after a call to WriterProvider.clearDestination() is made

defaults to false.

Returns:
true if the headers should be written before adding records to an empty entity, false otherwise

setHeaderWritingEnabled

public final void setHeaderWritingEnabled(boolean headerWritingEnabled)
Indicates whether or not to write headers to the output when writing records to an empty entity.

Note: write-only entities (i.e. obtained from WriterProvider) do not provide information about whether the output is empty or not. uniVocity will only attempt to write headers to such entities after a call to WriterProvider.clearDestination() is made

Parameters:
headerWritingEnabled - true if the headers should be written before adding records to an empty entity, false otherwise

getFormat

public final F getFormat()
Returns the input/output format settings for a given text. Each text format requires specific configuration, but they all share common settings from TextFormat

Returns:
the text format settings.

setFormat

public final void setFormat(F format)
Defines the input/output format settings for a given text. Each text format requires specific configuration, but they all share common settings from TextFormat

Parameters:
format - the text format settings.


Copyright © 2015 uniVocity Software Pty Ltd. All rights reserved.