Package org.refcodes.tabular

Interface Column<T>

Type Parameters:

T - The type managed by the Column.

All Superinterfaces:

org.refcodes.mixin.KeyAccessor<String>, org.refcodes.mixin.TypeAccessor<T>

All Known Subinterfaces:

FormattedColumn<T>

All Known Implementing Classes:

AbstractColumn, ColumnImpl, DateColumnImpl, ExceptionColumnImpl, FormattedColumnDecorator, FormattedColumnImpl, IntegerColumnImpl, StringColumnImpl, StringsColumnImpl

public interface Column<T>
extends org.refcodes.mixin.KeyAccessor<String>, org.refcodes.mixin.TypeAccessor<T>

Similar to a Column definition for a DB or a spread sheet (or, with reservations, a CSV file), a Column describes properties such as name (key) and type of elements related to that Column (e.g. the according elements of the Row lines).

Nested Class Summary

Nested classes/interfaces inherited from interface org.refcodes.mixin.KeyAccessor

org.refcodes.mixin.KeyAccessor.KeyBuilder<K extends Object,B extends org.refcodes.mixin.KeyAccessor.KeyBuilder<K,B>>, org.refcodes.mixin.KeyAccessor.KeyMutator<K extends Object>, org.refcodes.mixin.KeyAccessor.KeyProperty<K extends Object>

Nested classes/interfaces inherited from interface org.refcodes.mixin.TypeAccessor

org.refcodes.mixin.TypeAccessor.TypeMutator<T extends Object>, org.refcodes.mixin.TypeAccessor.TypeProperty<T extends Object>

Method Summary

Modifier and Type	Method	Description
boolean	contains(Record<?> aRecord)	Tests whether the Record contains a value identified by the Column instance's key and where the value's type is assignable to the Column instance's type.
T	fromStorageString(String aStringValue)	A Column implementation can provide its own text exchange format for the given objects.
T	fromStorageStrings(String[] aStringArray)	A Column implementation can provide its own text exchange format for the given objects.
T	get(Record<?> aRecord)	Retrieves a type correct value from the Record identified by the Column instance's key.
T	remove(Record<?> aRecord)	Removes an entry (key and value pair) from the provided Record matching the key and the type of the Column.
String	toPrintable(T aValue)	A Column implementation can provide its own printable format of the given objects; for example a human readable text representation of the value (or in very specialized cases even enriched with ANSI escape codes).
String	toStorageString(T aValue)	A Column implementation can provide its own text exchange format for the given objects.
String[]	toStorageStrings(T aValue)	A Column implementation can provide its own text exchange format for the given objects.

Methods inherited from interface org.refcodes.mixin.KeyAccessor

getKey

Methods inherited from interface org.refcodes.mixin.TypeAccessor

getType

Method Detail

toStorageString

String toStorageString(T aValue)

A Column implementation can provide its own text exchange format for the given objects. This method enables the Column to convert a value of the given type to a String and via fromStorageString(String) back to the value (bijective). This method supports data sinks (such as relational databases) which allow only a single value in a row's entry: In case T is an array type, then the storage String representation of the elements in that array are represented by a single returned String. In case a data sink (such as Amazon's SimpleDb) is to be addressed which provides dedicated support for multiple values in one row's entry, then the method toStorageStrings(Object) may be used instead.

Parameters:

aValue - the element to be converted to a String.

Returns:

The String representation of the value.

toStorageStrings

String[] toStorageStrings(T aValue)

A Column implementation can provide its own text exchange format for the given objects. This method enables the Column to convert a value of the given type to a String array and via fromStorageStrings(String[]) back to the value (bijective). This method supports data sinks (such as Amazon's SimpleDb) which provide dedicated support for multiple values in a row's entry: In case T is an array type, then the storage String representations of the elements in that array may be placed in dedicated entries of the returned String array. In case T is not an array type then the returned String array may contain just one value. In case data sinks (such as relational databases) are to be addressed which allow only a single value in a row's entry, then the method toStorageString(Object) may be used instead.

Parameters:

aValue - the element to be converted to a String array.

Returns:

The String array representation of the value.

fromStorageString

T fromStorageString(String aStringValue)
             throws ParseException

A Column implementation can provide its own text exchange format for the given objects. This method enables the Column to convert a String value to a value of the given type and via toStorageString(Object) back to the String (bijective). This method supports data sinks (such as relational databases) which allow only a single value in a row's entry: In case T is an array type, then the storage String representation of the elements in that array are represented by the single passed String. In case a data sink (such as Amazon's SimpleDb) is to be addressed which provides dedicated support for multiple values in one row's entry, then the method fromStorageStrings(String[]) may be used instead.

Parameters:

aStringValue - The value to be converted to a type instance.

Returns:

The type representation of the value.

Throws:

ParseException - in case parsing the String was not possible

fromStorageStrings

T fromStorageStrings(String[] aStringArray)
              throws ParseException

A Column implementation can provide its own text exchange format for the given objects. This method enables the Column to convert a String array value to a value of the given type and via toStorageStrings(Object) back to the String array (bijective). This method supports data sinks (such as Amazon's SimpleDb) which provide dedicated support for multiple values in a row's entry: In case T is an array type, then the storage String representations of the elements in that array may be placed in dedicated entries of the provided String array. In case T is not an array type then the passed String array may contain just one value. In case data sinks (such as relational databases) are to be addressed which allow only a single value in a row's entry, then the method fromStorageString(String) may be used instead.

Parameters:

aStringArray - The value to be converted to a type instance.

Returns:

The type representation of the value.

Throws:

ParseException - in case parsing the String was not possible

toPrintable

String toPrintable(T aValue)

A Column implementation can provide its own printable format of the given objects; for example a human readable text representation of the value (or in very specialized cases even enriched with ANSI escape codes). This method enables the Column to convert a value of the given type to a human readable text. The human readable text, in comparison to the method Object.toString() (or toStorageString(Object)) is not intended to be converted back to the actual value (not bijective). This method may be used a Header instance's method HeaderTemplate.toPrintable(Record).

Parameters:

aValue - the element to be converted to a human readable text.

Returns:

The human readable representation of the value.

contains

boolean contains(Record<?> aRecord)

Tests whether the Record contains a value identified by the Column instance's key and where the value's type is assignable to the Column instance's type. Only if them both criteria match, then true is returned. False is returned if there is no such value or the value is not assignable to the Column instance's type.

Parameters:

aRecord - The Record which to test if there is a value associated to the Column instance's key and if it can be casted to the Column instance's type.

Returns:

True in case the Record contains a value identified by the Column instance's key and where the value's type is assignable to the Column instance's type.

get

T get(Record<?> aRecord)
throws ColumnMismatchException

Retrieves a type correct value from the Record identified by the Column instance's key. In case the type of the Column instance does not match the value's type associated with the Column instance's key, then a ColumnMismatchException is thrown.

Parameters:

aRecord - The Record from which to retrieve the value associated to the Column instances key.

Returns:

The value from the Record associated to the Column instances key.

Throws:

ColumnMismatchException - in case the value in the Record associated with the Column instance's key does not fit the Column instance's type.

remove

T remove(Record<?> aRecord)
  throws ColumnMismatchException

Removes an entry (key and value pair) from the provided Record matching the key and the type of the Column.

Parameters:

aRecord - The Record from which to remove the related entry.

Returns:

The value related to the given Column instance's key or null if there was none such value found.

Throws:

ColumnMismatchException - in case the value in the Record associated with the Column instance's key does not fit the Column instance's type.