com.exponam.api.reader

Class Reader

java.lang.Object

com.exponam.api.reader.Reader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public final class Reader
extends java.lang.Object
implements java.io.Closeable

Reader is the single point of entry for accessing the contents of Exponam .BIG files.

A .BIG file contains one or more worksheets of data, where a worksheet is essentially a row and column representation of data. An individual data value is found at the intersection of three zero-based indices: a worksheet index, a row index, and a column index.

Data in Exponam .BIG files are strongly typed on a per-column basis. Depending on how the .BIG file was generated, a column may contain empty values. Depending on how data values are accessed via Reader, an empty value will be represented as either null or Optional.empty().

Non-empty values are eligible to be returned to you in a variety of forms. If you request the String representation of a value, it will e returned to you respecting any display formats that were applied when the .BIG file was generated. If you request an alternate type, type conversion will be applied if required and the value returned. In the event that no conversion is available, an unchecked Exception will be thrown.

For example, if you request that a value for a Boolean column be returned as a Date, you will receive an IllegalArgumentException.

Note that Reader is Closeable. Failure to call close() can result in dangling references to underlying structures.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Reader.ColumnTypes The types of columns that are supported in a .BIG file

Constructor Summary

Constructors

Constructor and Description
Reader(java.io.File bigFile, java.util.function.Supplier<java.lang.String> passwordSupplier) Constructs an object that can read from an Exponam .BIG file.

Method Summary

Modifier and Type	Method and Description
void	close() Close the Reader when through, allowing underlying resources to be properly released.
int	getColumnCount(int worksheetIndex) The number of columns contained in a worksheet.
java.lang.String	getColumnName(int worksheetIndex, int columnIndex) The name of a given column in a worksheet.
Reader.ColumnTypes	getColumnType(int worksheetIndex, int columnIndex) The type of data held in a given column in a worksheet.
int	getRowCount(int worksheetIndex) The number of rows contained in a worksheet.
void	getRowValues(int worksheetIndex, int startRow, int endRow, int[] columnIndexes, java.lang.reflect.Type[] desiredClassForColumns, java.util.function.BiConsumer<java.lang.Integer,java.lang.Object[]> rowConsumer) This method is recommended for reading large numbers of row-wise data.
<T> T	getValue(int worksheetIndex, int rowIndex, int columnIndex, java.lang.reflect.Type desiredClass) A data value held within a .BIG file, at the intersection of a worksheet index, row index, and column index, returned as an instance of desiredClass.
int	getWorksheetCount() The number of worksheets contained in the file.
java.lang.String	getWorksheetName(int worksheetIndex) The name given for a specific worksheet.

Methods inherited from class java.lang.Object

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

Constructor Detail

Reader

public Reader(java.io.File bigFile,
              java.util.function.Supplier<java.lang.String> passwordSupplier)
       throws java.io.IOException,
              com.exponam.core.reader.BigReader.UnsupportedFileVersionException

Constructs an object that can read from an Exponam .BIG file. Note that the password is made available to Reader via a Supplier. This is to facilitate password mechanisms by the caller and minimize the amount of time during which Reader retains access to that password.

Parameters:

bigFile - the Exponam .BIG file to be accessed

passwordSupplier - a caller-supplier function returning the password for the BigFile; can be null or return an empty String for unencrypted files

Throws:

java.io.IOException - if there is a problem accessing the file

BigReader.UnsupportedFileVersionException - if the file version is more recent than supported by this version of the API

Method Detail

getWorksheetCount

public int getWorksheetCount()

The number of worksheets contained in the file. Note: currently Exponam .BIG files contain a single worksheet.

Returns:

the number of worksheets

getWorksheetName

public java.lang.String getWorksheetName(int worksheetIndex)

The name given for a specific worksheet.

Parameters:

worksheetIndex - the zero-based worksheet index

Returns:

the worksheet name

getRowCount

public int getRowCount(int worksheetIndex)

The number of rows contained in a worksheet.

Parameters:

worksheetIndex - the zero-based worksheet index

Returns:

the number of rows in that worksheet

getColumnCount

public int getColumnCount(int worksheetIndex)

The number of columns contained in a worksheet.

Parameters:

worksheetIndex - the zero-based worksheet index

Returns:

the number of columns in that worksheet

getColumnName

public java.lang.String getColumnName(int worksheetIndex,
                                      int columnIndex)

The name of a given column in a worksheet.

Parameters:

worksheetIndex - the zero-based worksheet index

columnIndex - the zero-based column index

Returns:

the column name

getColumnType

public Reader.ColumnTypes getColumnType(int worksheetIndex,
                                        int columnIndex)

The type of data held in a given column in a worksheet.

Parameters:

worksheetIndex - the zero-based worksheet index

columnIndex - the zero-based column index

Returns:

the column type

getValue

public <T> T getValue(int worksheetIndex,
                      int rowIndex,
                      int columnIndex,
                      java.lang.reflect.Type desiredClass)

A data value held within a .BIG file, at the intersection of a worksheet index, row index, and column index, returned as an instance of desiredClass.

The supported data type conversions are:

• If desiredClass is String.class, any display formats specified within the .BIG file are applied to the value returned.
• If desiredClass is an Optional type, an empty data value is returned as Optional.empty().
• If desiredClass is not an Optional type, an empty data value is returned as null.
• The following type conversions are allowed:
• Boolean columns can be retrieved as
  • Boolean and Optional<Boolean>
  • Long, Integer, Short, Byte, Double, Float, BigDecimal, and Optional of any of these
• Date and DateTime columns can be retrieved as
  • java.util.Date and java.sql.Date, and Optional of either of these
  • Long and BigDecimal, and Optional of either of these
• Double columns can be retrieved as
  • Double and Optional<Double>
  • Long, Integer, Short, Byte, Float, BigDecimal, and Optional of any of these
• Long columns can be retrieved as
  • Long and Optional<Long>
  • Integer, Short, Byte, Double, Float, BigDecimal, and Optional of any of these
• String columns can be retrieved as
  • String and Optional<String> (note that Optional will never be empty)
• Time columns can be retrieved as
  • java.util.Date and java.sql.Date, and Optional of either of these (note that the time is expressed relative to a Date of January 1, 0001)
  • Long and BigDecimal, and Optional of either of these

Type Parameters:

T - the type to be returned, must match the desiredClass

Parameters:

worksheetIndex - the zero-based worksheet index

rowIndex - the zero-based row index

columnIndex - the zero-based column index

desiredClass - the desired type for the value

Returns:

the column type

getRowValues

public void getRowValues(int worksheetIndex,
                         int startRow,
                         int endRow,
                         int[] columnIndexes,
                         java.lang.reflect.Type[] desiredClassForColumns,
                         java.util.function.BiConsumer<java.lang.Integer,java.lang.Object[]> rowConsumer)

This method is recommended for reading large numbers of row-wise data. The types that are supported in desiredClassForColumns follow the same rules as given for getValue.

Parameters:

worksheetIndex - the zero-based worksheet index

startRow - the zero-based index for the first row in the range of rows to be retrieved

endRow - the zero-based index for the last row in the range of rows to be retrieved

columnIndexes - array of the zero-based column indexes for the columns to be retrieved

desiredClassForColumns - array of the desired type for for each of the columns to be retrieved

rowConsumer - the callback invoked for each row that is retrieved

close

public void close()
           throws java.io.IOException

Close the Reader when through, allowing underlying resources to be properly released.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - exception