Java SDK Documentation  12.0.0
com.vertica.sdk.StandardTypeCoercion Class Reference
Inheritance diagram for com.vertica.sdk.StandardTypeCoercion:
Inheritance graph
Collaboration diagram for com.vertica.sdk.StandardTypeCoercion:
Collaboration graph

Classes

enum  BooleanEvaluation
 
class  SpecialBigDecimal
 

Public Member Functions

 StandardTypeCoercion ()
 
ByteBuffer asBinaryBytes (Object value, int length, VerticaType type)
 
Boolean asBoolean (Object value, VerticaType type)
 
Boolean asBooleanByJava (Object value, VerticaType type)
 
Boolean asBooleanByNumeric (Object value, VerticaType type)
 
Boolean asBooleanByPerl (Object value, VerticaType type)
 
Boolean asBooleanByPython (Object value, VerticaType type)
 
Boolean asBooleanByVertica (Object value, VerticaType type)
 
ByteBuffer asCharBytes (Object value, int length, VerticaType type)
 
java.sql.Date asDate (Object value, VerticaType type)
 
Double asDouble (Object value, VerticaType type)
 
Long asLong (Object value, VerticaType type)
 
java.sql.Timestamp asTimestamp (Object value, VerticaType type)
 
BooleanEvaluation getBooleanEvaluation ()
 
DateFormat getDateFormat ()
 
DateFormat getDateParse ()
 
DateFormat getDefaultDateFormat ()
 
DateFormat getDefaultDateParse ()
 
DateFormat getDefaultTimestampFormat ()
 
DateFormat getDefaultTimestampParse ()
 
Iterator< Object > getListIterator (Object value)
 
Iterator< Map.Entry< String,
Object > > 
getMapIterator (Object value)
 
MetaType getMetaType (Object value)
 
Set< TypeCoercionPolicygetPolicy ()
 
DateFormat getTimestampFormat ()
 
DateFormat getTimestampParse ()
 
java.sql.Date parseDate (String value, VerticaType type)
 
java.sql.Timestamp parseTimestamp (String value, VerticaType type)
 
void setBooleanEvaluation (BooleanEvaluation boolEval)
 
void setDateFormat (DateFormat fmt)
 
void setDateParse (DateFormat fmt)
 
void setPolicy (Collection< TypeCoercionPolicy > policy)
 
void setTimestampFormat (DateFormat fmt)
 
void setTimestampParse (DateFormat fmt)
 

Protected Member Functions

Collection< TypeCoercionPolicygetDefaultPolicy ()
 
void invalidInputType (Object value, VerticaType type)
 
void invalidInputValue (Object value, VerticaType type)
 
SpecialBigDecimal parseNumber (char[] text)
 
void unsupportedType (Object value, VerticaType type)
 
void valueTooLarge (Object value, VerticaType type)
 

Detailed Description

StandardTypeCoercion implements standard type conversions. It provides some ability to configure how certain values (such as booleans and dates) are Interpreted or formatted.

The default policy favors errors and avoids modifying data. See getDefaultPolicy(). Values may be truncated if the policy includes TRUNCATE_VALUES.

Constructor & Destructor Documentation

com.vertica.sdk.StandardTypeCoercion.StandardTypeCoercion ( )

Create a default instance of StandardTypeCoercion using the default policy.

See Also
getDefaultPolicy()

Member Function Documentation

ByteBuffer com.vertica.sdk.NullTypeCoercion.asBinaryBytes ( Object  value,
int  length,
VerticaType  type 
)
inherited

Not supported; returns null or raises TypeCoercionException.

Implements com.vertica.sdk.TypeCoercion.

Boolean com.vertica.sdk.StandardTypeCoercion.asBoolean ( Object  value,
VerticaType  type 
)

Generates a Boolean (or null) value out of input values of various types, depending on the boolean evaluation strategy. Uses one of the various 'asBoolean' methods according to the current boolean evaluation strategy.

See Also
setBooleanEvaluation(BooleanEvaluation)
asBooleanByVertica(Object, VerticaType)
asBooleanByPerl(Object, VerticaType)
asBooleanByPython(Object, VerticaType)
asBooleanByJava(Object, VerticaType)
asBooleanByNumeric(Object, VerticaType)

Implements com.vertica.sdk.TypeCoercion.

Boolean com.vertica.sdk.StandardTypeCoercion.asBooleanByJava ( Object  value,
VerticaType  type 
)

Interprets a Boolean value in a similar manner as Java's Boolean#valueOf(String) function, which handles only Strings.

  • null values are null.

  • Boolean values are used as-is.

  • String values are evaluated via Boolean.valueOf(String).

Parameters
valueThe value being coerced.
typeThe target Vertica type, which is boolean.
Returns
value coerced to Boolean, potentially null.

Referenced by com.vertica.sdk.StandardTypeCoercion.asBoolean().

Boolean com.vertica.sdk.StandardTypeCoercion.asBooleanByNumeric ( Object  value,
VerticaType  type 
)

Interprets a Boolean value in a similar manner as C/C++, where numeric values and booleans aren't strictly separated. Rather than handling only integer numerics, this handles all numerics.

  • null values are null.

  • Boolean values are used as-is.

  • Number values are evaluated based on Number#doubleValue(). 0.0 is false and all other values are true.

  • All other types are invalid input types.

Parameters
valueThe value being coerced.
typeThe target Vertica type, which is boolean.
Returns
value coerced to Boolean, potentially null.

Referenced by com.vertica.sdk.StandardTypeCoercion.asBoolean().

Boolean com.vertica.sdk.StandardTypeCoercion.asBooleanByPerl ( Object  value,
VerticaType  type 
)

Interprets a Boolean value in a similar manner as Perl does. Unlike Perl which treats undef as false, the null value will give a null Boolean. Otherwise, behavior follows the Perl behavior as closely as possible.

  • null values are null.

  • Boolean values are used as-is.

  • String values are false if empty (length() == 0) or if equal to "0". Strings are true otherwise. Whitespace is NOT ignored.

  • Number values are evaluated based on doubleValue(). 0.0 is false and all other values are True.

  • Collection and Map values are false if empty (size() == 0) and true otherwise.

  • All other types are true. Therefore, this will never result in an invalid input type.

Parameters
valueThe value being coerced.
typeThe target Vertica type, which is boolean.
Returns
value coerced to Boolean, potentially null.

Referenced by com.vertica.sdk.StandardTypeCoercion.asBoolean().

Boolean com.vertica.sdk.StandardTypeCoercion.asBooleanByPython ( Object  value,
VerticaType  type 
)

Interprets a Boolean value in a similar manner as Python does. Unlike Python which treats None as False, the null value will give a null Boolean. Otherwise, behavior follows the Python language specification. See "5.10 Boolean operations" in the Python 2.x reference on expressions.

  • null values are null.

  • Boolean values are used as-is.

  • String values are false if empty (length() == 0) and true otherwise. Whitespace is NOT ignored.

  • Number values are evaluated based on doubleValue(). 0.0 is false and all other values are True.

  • Collection and Map values are false if empty (size() == 0) and true otherwise.

  • All other types are true. Therefore, this will never result in an invalid input type.

Parameters
valueThe value being coerced.
typeThe target Vertica type, which is boolean.
Returns
value coerced to Boolean, potentially null.

Referenced by com.vertica.sdk.StandardTypeCoercion.asBoolean().

Boolean com.vertica.sdk.StandardTypeCoercion.asBooleanByVertica ( Object  value,
VerticaType  type 
)

Interprets a Boolean value in a similar manner as Vertica does internally.

  • null values are null.

  • Boolean values are used as-is.

  • The following String values are true, after trimming leading and trailing whitespace and ignoring case: 't', 'true', 'y', 'yes', '1'.

  • The following String values are false, after trimming leading and trailing whitespace and ignoring case: 'f', 'false', 'n', 'no', '0'.

  • All other String values are invalid input values.

  • Number values are evaluated based on doubleValue(). 0.0 is false and 1.0 is true. All other values are invalid input values.

  • All other types are invalid input types.

Parameters
valueThe value being coerced.
typeThe target Vertica type, which is boolean.
Returns
value coerced to Boolean, potentially null.

Referenced by com.vertica.sdk.StandardTypeCoercion.asBoolean().

ByteBuffer com.vertica.sdk.StandardTypeCoercion.asCharBytes ( Object  value,
int  length,
VerticaType  type 
)

Generates a ByteBuffer with the string representation of an object. Generally uses the same approach as Vertica's vsql presentation format for analogous types. Unknown types will use Java's String#valueOf(Object).

The value will be truncated to length when necessary if TRUNCATE_VALUES is specified in the policy. Otherwise values that are too long will return in either a null return value or a TypeCoercionException according to the policy (FAIL_INVALID_INPUT_VALUE).

In agreement with how 'char' values are stored in Vertica, trailing spaces will be removed if the type is 'char'.

Specifically, the following describes the textual representation of various types, which then undergoes truncation and trimming as necessary.

See Also
VerticaType::isChar()

Implements com.vertica.sdk.TypeCoercion.

java.sql.Date com.vertica.sdk.StandardTypeCoercion.asDate ( Object  value,
VerticaType  type 
)

Generate a java.sql.Date representation of the provided object.

See Also
parseDate(String, VerticaType)

Implements com.vertica.sdk.TypeCoercion.

Double com.vertica.sdk.StandardTypeCoercion.asDouble ( Object  value,
VerticaType  type 
)

Generates a Double representation of the provided object.

  • null values are null.

  • Number values use Number#doubleValue().

  • Strings are parsed by the following rules. Violations are invalid input values. Note that the double data type has a limited range of precision and magnitude. Some precision may be lost. Extreme values may be represented as Infinity or -Infinity.

    • A hexidecimal integer value starting with '0x' or '0X' with optional leading '-' or '+'.

    • 'Infinity' (case insensitive) with optional leading '-' or '+'.

    • 'NaN' (case insensitive) with optional leading '-' or '+'.

    • A decimal number with or without scientific notation, with optional leading '-' or '+'

  • All other types are invalid input types.

Implements com.vertica.sdk.TypeCoercion.

Long com.vertica.sdk.StandardTypeCoercion.asLong ( Object  value,
VerticaType  type 
)

Generates a Long representation of the provided object.

  • null values are null.

  • Number values use Number#doubleValue(). This usually implies truncation of any fractional part of the value, regardless of the truncation policy.

  • Strings are parsed by the following rules. Violations are invalid input values. Note that the long data type has a limited range of magnitude. Values outside of this range are invalid input values. Values with fractional parts are truncated.

    • A hexidecimal integer value starting with '0x' or '0X' with optional leading '-' or '+'.

    • A decimal number with or without scientific notation, with optional leading '-' or '+'

  • All other types are invalid input types.

Implements com.vertica.sdk.TypeCoercion.

java.sql.Timestamp com.vertica.sdk.StandardTypeCoercion.asTimestamp ( Object  value,
VerticaType  type 
)

Generate a java.sql.Timestamp representation of the provided object.

See Also
parseTimestamp(String, VerticaType)

Implements com.vertica.sdk.TypeCoercion.

BooleanEvaluation com.vertica.sdk.StandardTypeCoercion.getBooleanEvaluation ( )

Get the boolean evaluation strategy. The default is VERTICA.

Returns
The current boolean evaluation strategy.
DateFormat com.vertica.sdk.StandardTypeCoercion.getDateFormat ( )

Get the DateFormat used for formatting date types. This is used during asCharBytes for appropriately typed objects.

Returns
The format in use.
See Also
asCharBytes(Object, int, VerticaType)
DateFormat com.vertica.sdk.StandardTypeCoercion.getDateParse ( )

Retrieve the current DateFormat used for parsing java.sql.Date values in parseDate(String, VerticaType). Does not return null.

Returns
The format in use.
See Also
getDefaultDateParse()
parseDate(String, VerticaType)
DateFormat com.vertica.sdk.StandardTypeCoercion.getDefaultDateFormat ( )

Get the default DateFormat used for formatting date types to Strings. The format is 'yyyy-MM-dd' in the JVM default timezone. This is used during asCharBytes for appropriately typed objects.

Returns
The default format used by new instances.
See Also
asCharBytes(Object, int, VerticaType)

Referenced by com.vertica.sdk.StandardTypeCoercion.setDateFormat().

DateFormat com.vertica.sdk.StandardTypeCoercion.getDefaultDateParse ( )

Get the default DateFormat used for parsing date types from Strings. The format is 'yyyy-MM-dd' in the JVM default timezone and is not lenient.

For more flexibility, override parseDate(String, VerticaType) or install a different date format.

See Also
parseDate(String, VerticaType)
setDateParse(DateFormat)
Returns
The default format used by new instances.

Referenced by com.vertica.sdk.StandardTypeCoercion.setDateParse().

Collection<TypeCoercionPolicy> com.vertica.sdk.NoopTypeCoercion.getDefaultPolicy ( )
protectedinherited

Provides the default policy installed by the constructor.

For NoopTypeCoercion, the default policy favors errors and avoids modifying data:

  • FAIL_SDK_UNSUPPORTED_TYPE
  • FAIL_UNSUPPORTED_TYPE
  • FAIL_INVALID_INPUT_TYPE
  • FAIL_INVALID_INPUT_VALUE
DateFormat com.vertica.sdk.StandardTypeCoercion.getDefaultTimestampFormat ( )

Get the default DateFormat used for formatting timestamp types to Strings. The format is 'yyyy-MM-dd HH:mm:ss.SSS' in the JVM default timezone. This is used during asCharBytes for appropriately typed objects.

Returns
The default format used by new instances.
See Also
asCharBytes(Object, int, VerticaType)

Referenced by com.vertica.sdk.StandardTypeCoercion.setTimestampFormat().

DateFormat com.vertica.sdk.StandardTypeCoercion.getDefaultTimestampParse ( )

Get the default DateFormat used for parsing timestamp types from Strings. The format is 'yyyy-MM-dd HH:mm:ss.SSS' in the JVM default timezone and is not lenient.

For more flexibility, override parseTimestamp(String, VerticaType) or install a different date format.

See Also
parseTimestamp(String, VerticaType)
setTimestampParse(DateFormat)
Returns
The default format used by new instances.

Referenced by com.vertica.sdk.StandardTypeCoercion.setTimestampParse().

Iterator<Object> com.vertica.sdk.NoopTypeCoercion.getListIterator ( Object  value)
inherited

Provides an Iterator over Objects for a given Iterable input.

Parameters
valueSomething implementing Iterable<Object>

Implements com.vertica.sdk.TypeCoercion.

Iterator<Map.Entry<String,Object> > com.vertica.sdk.NoopTypeCoercion.getMapIterator ( Object  value)
inherited

Provides an Iterator over map entries for a given Map.

Internal maps are assumed to have String keys. A ClassCastException will eventually result if there are internal maps with keys that are not Strings.

Parameters
valueSomething implementing Map<String,Object>

Implements com.vertica.sdk.TypeCoercion.

MetaType com.vertica.sdk.NoopTypeCoercion.getMetaType ( Object  value)
inherited

Detects Java standard Map and Iterable types.

Internal maps are assumed to have String keys. A ClassCastException will result if there are internal maps with keys that are not Strings.

Implements com.vertica.sdk.TypeCoercion.

DateFormat com.vertica.sdk.StandardTypeCoercion.getTimestampFormat ( )

Get the current DateFormat used for formatting timestamp types. This is used during asCharBytes for appropriately typed objects.

Returns
The format in use.
See Also
asCharBytes(Object, int, VerticaType)
DateFormat com.vertica.sdk.StandardTypeCoercion.getTimestampParse ( )

Retrieve the current DateFormat used for parsing java.sql.Timestamp values in parseTimestamp(String, VerticaType). Does not return null.

Returns
The format in use.
See Also
getDefaultTimestampParse()
parseTimestamp(String, VerticaType)
void com.vertica.sdk.StandardTypeCoercion.invalidInputValue ( Object  value,
VerticaType  type 
)
protected
java.sql.Date com.vertica.sdk.StandardTypeCoercion.parseDate ( String  value,
VerticaType  type 
)

Parse a date from a String using the current date parsing format.

Note that java.sql.Date specifies that values should be normalized by setting all non-day units to 0. This is not necessary or expected of return values from parseDate.

Parameters
valueThe String value being coerced, which is not null.
typeThe target Vertica type, which is a date type.
Returns
The input value as a date, or null.
See Also
setDateParse(DateFormat)
getDefaultDateParse()

Referenced by com.vertica.sdk.StandardTypeCoercion.asDate().

SpecialBigDecimal com.vertica.sdk.StandardTypeCoercion.parseNumber ( char[]  text)
protected

Parses a textual representation of a number into a SpecialBigDecimal. Input text is trimmed of whitespace, then evaluated as a perfect fit to:

  • A hexidecimal integer value starting with '0x' or '0X' with optional leading '-' or '+'.

  • 'Infinity' (case insensitive) with optional leading '-' or '+'.

  • 'NaN' (case insensitive) with optional leading '-' or '+'.

  • A decimal number with or without scientific notation, with optional leading '-' or '+'.

Parameters
textA string as a character array.
Returns
A SpecialBigDecimal representing the value of the text, whether that is a BigDecimal value or a special non-real value.

Referenced by com.vertica.sdk.StandardTypeCoercion.asDouble(), and com.vertica.sdk.StandardTypeCoercion.asLong().

java.sql.Timestamp com.vertica.sdk.StandardTypeCoercion.parseTimestamp ( String  value,
VerticaType  type 
)

Parse a timestamp from a String using the current timestamp parsing format. Because DateFormat#parse(String, ParsePosition) returns a java.sql.Date, the precision of this operation is only milliseconds, which is less than Vertica's possible precision of microseconds.

Note that timestamptz (aka 'timestamp with time zone') and timestamp values are parsed in the same manner, regardless of the current session's timezone.

Parameters
valueThe String value being coerced, which is not null.
typeThe target Vertica type, which is either timestamp or timestamptz.
Returns
A timestamp value, or null.
See Also
setTimestampParse(DateFormat)
getDefaultTimestampParse()

Referenced by com.vertica.sdk.StandardTypeCoercion.asTimestamp().

void com.vertica.sdk.StandardTypeCoercion.setBooleanEvaluation ( BooleanEvaluation  boolEval)
void com.vertica.sdk.StandardTypeCoercion.setDateFormat ( DateFormat  fmt)

Set the DateFormat used for formatting date types. This is used during asCharBytes for appropriately typed objects. Only the format method will be used; other methods do not need to be implemented.

Parameters
fmtThe format to use.
See Also
asCharBytes(Object, int, VerticaType)
void com.vertica.sdk.StandardTypeCoercion.setDateParse ( DateFormat  fmt)

Set the DateFormat used for parsing java.sql.Date values in parseDate. If null, the default date parse format is used.

Note: Non-Lenient DateFormats are strongly encouraged. Lenient date formats can cause surprising results in some scenarios.

Parameters
fmtThe format to use.
See Also
getDefaultDateParse()
parseDate(String, VerticaType)
void com.vertica.sdk.NullTypeCoercion.setPolicy ( Collection< TypeCoercionPolicy policy)
inherited

Sets the policies for this TypeCoercion instance. Policies generally dictate which scenarios generate exceptions and allow for different error handling choices without implementing a new TypeCoercion class.

Parameters
policyThe policy collection
See Also
TypeCoercionPolicy
getPolicy()

Implements com.vertica.sdk.TypeCoercion.

Referenced by com.vertica.sdk.NullTypeCoercion.NullTypeCoercion().

void com.vertica.sdk.StandardTypeCoercion.setTimestampFormat ( DateFormat  fmt)

Set the DateFormat used for formatting timestamp types. This is used during asCharBytes for appropriately typed objects. Only the format method will be used; other methods do not need to be implemented.

Parameters
fmtThe format to use.
See Also
asCharBytes(Object, int, VerticaType)
void com.vertica.sdk.StandardTypeCoercion.setTimestampParse ( DateFormat  fmt)

Set the DateFormat used for parsing java.sql.Timestamp values in parseTimestamp. If null, the default timestamp parse format is used.

Note: Non-Lenient DateFormats are strongly encouraged. Lenient date formats can cause surprising results in some scenarios.

Parameters
fmtThe format to use.
See Also
getDefaultTimestampParse()
parseTimestamp(String, VerticaType)
void com.vertica.sdk.NullTypeCoercion.unsupportedType ( Object  value,
VerticaType  type 
)
protectedinherited
void com.vertica.sdk.NoopTypeCoercion.valueTooLarge ( Object  value,
VerticaType  type 
)
protectedinherited

Throws a TypeCoercionException with a TRUNCATE_VALUES cause if the policy includes FAIL_INVALID_INPUT_VALUE. Otherwise does nothing.

This should only be called if the policy does not request truncation via TRUNCATE_VALUES.

Parameters
valueThe value being coerced.
typeThe target type.
See Also
getPolicy()
#setPolicy(Collection)

Referenced by com.vertica.sdk.NoopTypeCoercion.asCharBytes(), and com.vertica.sdk.StandardTypeCoercion.asCharBytes().