Module org.tentackle.sql

Package org.tentackle.sql

Interface DataType<T>

Type Parameters:

T - the java type described by this data type

All Known Implementing Classes:

AbstractDataType, AbstractDateTimeType, AbstractNumberType, BigDecimalType, BinaryType, BMoneyType, BooleanPrimitiveType, BooleanType, BytePrimitiveType, ByteType, CharacterPrimitiveType, CharacterType, ConvertibleType, DateType, DMoneyType, DoublePrimitiveType, DoubleType, FloatPrimitiveType, FloatType, IntegerPrimitiveType, IntegerType, LargeStringType, LocalDateTimeType, LocalDateType, LocalTimeType, LongPrimitiveType, LongType, ShortPrimitiveType, ShortType, StringType, TimestampType, TimeType

public interface DataType<T>

The data type.
Describes a type from the model perspective and maps it to one or more SqlTypes, each corresponding to a database column.

Implementations must be annotated with @Service(DataType.class). DataTypes are singletons and loaded by the DataTypeFactory. Hence, they must not maintain any state and the == operator is logically equivalent to equals().

A predefined set of commonly used Java- and Tentackle-types is already provided, but the application may define their own types (that's why DataType is not an enum).
The combination of javaName and variant is unique. The javaName is the plain classname without the package, since we don't want the model to refer to classes with the same name, but in different packages (usually a bad idea anyway).

The use of DataTypes is threefold:

1. for the model's attributes that refer to known types
2. for the wurblets to generate type-specific code
3. for application-specific types used at runtime by the peristence layer

Notes for implementors of application-specific data types:
The method isPredefined() must return false. Otherwise the wurblets assume that type-specific methods exist and generate uncompilable code.
Furthermore, since DataTypes refer to the corresponding Java type, they should reside in a separate module the java type's module does not depend on. Otherwise all application modules would refer to the tentackle-sql module, which is not desired for the PDO module(s).

Finally, the DataType's module must be made known to the following maven plugins:

• wurbelizer plugin: add as wurbletDependency (see the wurbelizer docs)
• tentackle sql plugin: add as plugin dependency

Method Summary

Modifier and Type	Method	Description
T	get(Backend backend, java.sql.ResultSet resultSet, int[] pos, boolean mapNull, java.lang.Integer size)	Gets the object from a result set. Must be implemented if isPredefined() returns false.
int	getColumnCount()	Gets the number of database columns. A tentackle type may be mapped to more than one column for multi-column types such as BMoney.
java.lang.String	getColumnGetter(int index)	Gets the java getter name of a column.
java.util.Optional<java.lang.String>	getColumnSuffix(int index)	Gets the optional suffix. Suffixes usually begin with an underscore.
java.lang.Object	getColumnValue(int index, T value)	Gets the value of a column.
java.util.Optional<java.lang.String>	getCommentSuffix(int index)	Gets the optional comment suffix. If present, it will be appended to the comment.
java.lang.String	getDataTypeConstant()	Gets the name of the datatype constant.
java.lang.String	getJavaType()	Gets the name of the Java type.
int	getScale(int index, java.lang.Integer scale)	Gets the column scale.
int	getSize(int index, java.lang.Integer size)	Gets the column size.
SqlType	getSqlType(int index)	Gets the SQL type.
java.lang.String	getVariant()	Gets the optional variant of the type.
boolean	isBool()	Returns whether this is a boolean or Boolean type.
boolean	isDateOrTime()	Returns whether this is a date and/or time type.
boolean	isDowncastNecessary()	For certain numeric types, downcasts are necessary when assigning literals.
boolean	isJavaTypeGenerified()	Returns whether the inner type describes a generified java type. Implies isModelProvidingInnerType().
boolean	isLiteralSupported()	Returns whether this type can be used literally in a query String.
boolean	isMapNullSupported()	Returns whether this type supports mapping null values to some well-defined constant.
boolean	isModelProvidingInnerType()	Returns whether the model provides an inner type.
boolean	isMutable()	Returns whether type is a mutable java object. Mutable objects may change their state and must implement Freezable.
boolean	isNumeric()	Returns whether this is a numeric type.
boolean	isPredefined()	Returns whether this is a predefined type.
boolean	isPrimitive()	Returns whether type is a primitive.
boolean	isUTCSupported()	Returns whether this type supports the UTC option.
java.lang.Object[]	set(Backend backend, java.sql.PreparedStatement statement, int pos, T object, boolean mapNull, java.lang.Integer size)	Sets the object into a prepared statement. Must be implemented if isPredefined() returns false.
java.lang.Object	set(Backend backend, java.sql.PreparedStatement statement, int pos, T object, int index, boolean mapNull, java.lang.Integer size)	Sets a column of an object into a prepared statement. Must be implemented if isPredefined() returns false.
java.lang.String	toLiteral(java.lang.String str)	Takes the string representation of a value and converts it to an SQL literal. Some types need single quotes, for example.
DataType<?>	toNonPrimitive()	Gets the non-primitive type if this is a primitive.
java.util.Optional<DataType<?>>	toPrimitive()	Gets the primitive type if this is a non-primitive.
java.lang.String	toString(T object)	Takes an object and converts it to a string that can in turn be parsed with valueOf(String). The method is used to print a literal (for example the default value of a dumped attribute).
T	valueOf(java.lang.String str)	Parses a string and converts to the value of this type. The method is used to parse a literal (for example the default value defined in the model).
java.lang.String	valueOfLiteralToCode(java.lang.String str)	Creates the java code to apply the valueOf method to a String.

Method Detail

getJavaType

java.lang.String getJavaType()

Gets the name of the Java type.

Returns:

the type

getVariant

java.lang.String getVariant()

Gets the optional variant of the type.

Returns:

the variant, empty string if none, never null

isPredefined

boolean isPredefined()

Returns whether this is a predefined type.

Returns:

true if explicit methods provided by the persistence layer, false if generic methods must be used

isPrimitive

boolean isPrimitive()

Returns whether type is a primitive.

Returns:

true if primitive

toNonPrimitive

DataType<?> toNonPrimitive()

Gets the non-primitive type if this is a primitive.

Returns:

the non-primitive type, this type if it is already a non-primitive

toPrimitive

java.util.Optional<DataType<?>> toPrimitive()

Gets the primitive type if this is a non-primitive.

Returns:

the primitive type if there is one

isMutable

boolean isMutable()

Returns whether type is a mutable java object.
Mutable objects may change their state and must implement Freezable.

Returns:

true if mutable and freezable

isNumeric

boolean isNumeric()

Returns whether this is a numeric type.

Returns:

true if numeric

isDateOrTime

boolean isDateOrTime()

Returns whether this is a date and/or time type.

Returns:

true if time, date or timestamp

isBool

boolean isBool()

Returns whether this is a boolean or Boolean type.

Returns:

true if bool

getColumnCount

int getColumnCount()

Gets the number of database columns.
A tentackle type may be mapped to more than one column for multi-column types such as BMoney.

Returns:

default is 1

getSqlType

SqlType getSqlType(int index)

Gets the SQL type.

Parameters:

index - the column index

Returns:

the SQL type

getSize

int getSize(int index,
            java.lang.Integer size)

Gets the column size.

Parameters:

index - the column index

size - the size from the model

Returns:

the column size

getScale

int getScale(int index,
             java.lang.Integer scale)

Gets the column scale.

Parameters:

index - the column index

scale - the scale from the model

Returns:

the column scale

getColumnValue

java.lang.Object getColumnValue(int index,
                                T value)

Gets the value of a column.

Parameters:

index - the column index

value - the datatype's value according to the model

Returns:

the column's value

getColumnGetter

java.lang.String getColumnGetter(int index)

Gets the java getter name of a column.

Parameters:

index - the datatype's value according to the model

Returns:

the column's getter name, empty string if this is a single column type

getColumnSuffix

java.util.Optional<java.lang.String> getColumnSuffix(int index)

Gets the optional suffix.
Suffixes usually begin with an underscore.

Parameters:

index - the column index

Returns:

the optional suffix

getCommentSuffix

java.util.Optional<java.lang.String> getCommentSuffix(int index)

Gets the optional comment suffix.
If present, it will be appended to the comment.

Important: for datatypes with more than one column, none or exactly one should be without suffix. See WurbletArgument in tentackle-wurblets.

Parameters:

index - the column index

Returns:

the optional suffix

isMapNullSupported

boolean isMapNullSupported()

Returns whether this type supports mapping null values to some well-defined constant.

Returns:

true if mapNull supported

isUTCSupported

boolean isUTCSupported()

Returns whether this type supports the UTC option.

Returns:

true if UTC supported

isDowncastNecessary

boolean isDowncastNecessary()

For certain numeric types, downcasts are necessary when assigning literals.

Returns:

true if downcast is necessary

isModelProvidingInnerType

boolean isModelProvidingInnerType()

Returns whether the model provides an inner type.

Returns:

true if inner type is specified within angle brackets, false if standard type

isJavaTypeGenerified

boolean isJavaTypeGenerified()

Returns whether the inner type describes a generified java type.
Implies isModelProvidingInnerType().

Returns:

true if javaType<T>, else simple type

isLiteralSupported

boolean isLiteralSupported()

Returns whether this type can be used literally in a query String.

Returns:

true if literal String supported, else false

toLiteral

java.lang.String toLiteral(java.lang.String str)

Takes the string representation of a value and converts it to an SQL literal.
Some types need single quotes, for example.

Parameters:

str - the value string

Returns:

the SQL literal

valueOf

T valueOf(java.lang.String str)

Parses a string and converts to the value of this type.
The method is used to parse a literal (for example the default value defined in the model).

Notice: the method doesn't use any locale, so the results are always the same regardless of the JVM's locale.

Parameters:

str - the source string

Returns:

the value

valueOfLiteralToCode

java.lang.String valueOfLiteralToCode(java.lang.String str)

Creates the java code to apply the valueOf method to a String.

Parameters:

str - the literal to be parsed

Returns:

the java code

toString

java.lang.String toString(T object)

Takes an object and converts it to a string that can in turn be parsed with valueOf(String).
The method is used to print a literal (for example the default value of a dumped attribute).

Notice: the method doesn't use any locale, so the results are always the same regardless of the JVM's locale.

Parameters:

object - the object of this DataType

Returns:

the printable string

getDataTypeConstant

java.lang.String getDataTypeConstant()

Gets the name of the datatype constant.

Returns:

the DT_...

set

java.lang.Object[] set(Backend backend,
                       java.sql.PreparedStatement statement,
                       int pos,
                       T object,
                       boolean mapNull,
                       java.lang.Integer size)
                throws java.sql.SQLException

Sets the object into a prepared statement.
Must be implemented if isPredefined() returns false. Not invoked by framework otherwise.

Parameters:

backend - the database backend

statement - the prepared statement

pos - the position of the first SQL value

object - the object, may be null

mapNull - true if map null-values to non-null values

size - the optional size specified in the model

Returns:

the values stored in the prepared statement

Throws:

java.sql.SQLException - if failed

set

java.lang.Object set(Backend backend,
                     java.sql.PreparedStatement statement,
                     int pos,
                     T object,
                     int index,
                     boolean mapNull,
                     java.lang.Integer size)
              throws java.sql.SQLException

Sets a column of an object into a prepared statement.
Must be implemented if isPredefined() returns false. Not invoked by framework otherwise.

Parameters:

backend - the database backend

statement - the prepared statement

pos - the position of the first SQL value

object - the object, may be null

index - the column index

mapNull - true if map null-values to non-null values

size - the optional size specified in the model

Returns:

the object stored in the prepared statement

Throws:

java.sql.SQLException - if failed

get

T get(Backend backend,
      java.sql.ResultSet resultSet,
      int[] pos,
      boolean mapNull,
      java.lang.Integer size)
throws java.sql.SQLException

Gets the object from a result set.
Must be implemented if isPredefined() returns false. Not invoked by framework otherwise.

Parameters:

backend - the database backend

resultSet - the result set

pos - the column positions in the result set

mapNull - true if unmap null-values from non-null values

size - the optional size specified in the model

Returns:

the object or null if column(s) IS NULL

Throws:

java.sql.SQLException - if failed