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, I18NTextType, InstantType, IntegerPrimitiveType, IntegerType, LargeStringType, LocalDateTimeType, LocalDateType, LocalTimeType, LongPrimitiveType, LongType, OffsetDateTimeType, OffsetTimeType, ShortPrimitiveType, ShortType, StringType, TimestampType, TimeType, UUIDType, ZonedDateTimeType
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 persistence 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
    List<String>
    createColumnNames(Backend backend, String columnName)
    Creates a list of column names.
    String
    createColumnNamesAsString(Backend backend, String columnName, String separator)
    Creates a list of column names as a concatenated string.
    The string can be used in SQL INSERT and UPDATE statements.
    T
    get(Backend backend, ResultSet resultSet, int[] pos, boolean mapNull, Integer size)
    Gets the object from a result set.
    Must be implemented if isPredefined() returns false.
    String
    getColumnAlias(int index)
    Gets the alias name of a column.
    int
    getColumnCount(Backend backend)
    Gets the number of database columns.
    A tentackle type may be mapped to more than one column for multi-column types such as BMoney.
    String
    getColumnGetter(int index, String varName)
    Returns the java code to get the value of a column.
    Optional<String>
    getColumnSuffix(Backend backend, int index)
    Gets the optional suffix.
    Suffixes usually begin with an underscore.
    Object
    getColumnValue(Backend backend, int index, T value)
    Gets the value of a column.
    Optional<String>
    getCommentSuffix(Backend backend, int index)
    Gets the optional comment suffix.
    If present, it will be appended to the comment.
    String
    getDataTypeConstant()
    Gets the name of the datatype constant.
    String
    getJavaType()
    Gets the name of the Java type.
    Object
    getMappedNullValue(Backend backend, int index)
    Gets the mapped non-null value that represents the model's null value.
    The method throws a BackendException, if !isMapNullSupported().
    int
    getScale(Backend backend, int index, Integer scale)
    Gets the column scale.
    The scale may be differently aligned according to the backend.
    int
    getSize(Backend backend, int index, Integer size)
    Gets the column size.
    Sizes may be differently aligned according to the backend.
    int[]
    getSortableColumns()
    Gets the indexes to the sortable columns.
    The number and order of the indexes is reflected in the generated order-by SQL clause.
    SqlType
    getSqlType(Backend backend, int index)
    Gets the SQL type.
    For predefined types, the type must be the same for all backends and the backend argument may be null.
    Application specific types, however, can use different sql types for different backends and for those types the backend argument is always valid.
    String
    getVariant()
    Gets the optional variant of the type.
    boolean
    isBool()
    Returns whether this is a boolean or Boolean type.
    boolean
    isColumnCountBackendSpecific()
    Returns whether the number of columns is backend-specific.
    For such types the following restrictions apply: no CN_... will be generated for the individual columns, just the column basename they cannot be used as wurblet arguments (to generate the WHERE-clause) the application cannot refer to a column in a backend-agnostic way
    boolean
    isDateOrTime()
    Returns whether this is a date and/or time type.
    boolean
    isDowncastNecessary()
    For certain numeric types, a downcast is necessary when assigning literals.
    boolean
    isJavaTypeGenerified()
    Returns whether the inner type describes a generified java type.
    Implies isModelProvidingInnerType().
    boolean
    isLiteralSupported(Integer index)
    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
    isTimezoneApplicable()
    Returns whether a Calendar-timezone can be applied to this date and/or time related type.
    Only for types where methods with Calendar argument are provided in ResultSet and PreparedStatement.
    boolean
    isUTCSupported()
    Returns whether this type supports the UTC option.
    Object[]
    set(Backend backend, PreparedStatement statement, int pos, T object, boolean mapNull, Integer size)
    Sets the object into a prepared statement.
    Must be implemented if isPredefined() returns false.
    Object
    set(Backend backend, PreparedStatement statement, int pos, T object, int index, boolean mapNull, Integer size)
    Sets a column of an object into a prepared statement.
    Must be implemented if isPredefined() returns false.
    String
    toLiteral(String str, Integer index)
    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.
    Optional<DataType<?>>
    toPrimitive()
    Gets the primitive type if this is a non-primitive.
    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(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).
    String
    valueOfLiteralToCode(String str, Integer index)
    Creates the java code to apply the valueOf method to a String.

  • Method Details

    • getJavaType

      String getJavaType()
      Gets the name of the Java type.
      Returns:
      the type

    • getVariant

      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

      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

    • isTimezoneApplicable

      boolean isTimezoneApplicable()
      Returns whether a Calendar-timezone can be applied to this date and/or time related type.
      Only for types where methods with Calendar argument are provided in ResultSet and PreparedStatement.
      Returns:
      true if methods exist with timezone correction

    • isBool

      boolean isBool()
      Returns whether this is a boolean or Boolean type.
      Returns:
      true if bool

    • isColumnCountBackendSpecific

      boolean isColumnCountBackendSpecific()
      Returns whether the number of columns is backend-specific.
      For such types the following restrictions apply:
      • no CN_... will be generated for the individual columns, just the column basename
      • they cannot be used as wurblet arguments (to generate the WHERE-clause)
      • the application cannot refer to a column in a backend-agnostic way
      Returns:
      false if not backend-specific (default), true if varying

    • getColumnCount

      int getColumnCount(Backend backend)
      Gets the number of database columns.
      A tentackle type may be mapped to more than one column for multi-column types such as BMoney.
      Parameters:
      backend - the backend, ignored if !isColumnCountBackendSpecific()
      Returns:
      default is 1

    • getSortableColumns

      int[] getSortableColumns()
      Gets the indexes to the sortable columns.
      The number and order of the indexes is reflected in the generated order-by SQL clause.
      Returns:
      the column indexes, null or empty if datatype is not sortable in a meaningful manner by the database

    • getSqlType

      SqlType getSqlType(Backend backend, int index)
      Gets the SQL type.
      For predefined types, the type must be the same for all backends and the backend argument may be null.
      Application specific types, however, can use different sql types for different backends and for those types the backend argument is always valid.
      Parameters:
      backend - the backend, not used by predefined types
      index - the column index
      Returns:
      the SQL type

    • getSize

      int getSize(Backend backend, int index, Integer size)
      Gets the column size.
      Sizes may be differently aligned according to the backend.
      Parameters:
      backend - the backend
      index - the column index
      size - the size from the model
      Returns:
      the column size

    • getScale

      int getScale(Backend backend, int index, Integer scale)
      Gets the column scale.
      The scale may be differently aligned according to the backend.
      Parameters:
      backend - the backend
      index - the column index
      scale - the scale from the model
      Returns:
      the column scale

    • getColumnValue

      Object getColumnValue(Backend backend, int index, T value)
      Gets the value of a column.
      Parameters:
      backend - the backend, ignored if !isColumnCountBackendSpecific()
      index - the column index
      value - the datatype's value according to the model
      Returns:
      the column's value

    • getColumnGetter

      String getColumnGetter(int index, String varName)
      Returns the java code to get the value of a column.
      Parameters:
      index - the column index
      varName - the java variable name
      Returns:
      the java code, empty string if this is a single column type

    • getColumnAlias

      String getColumnAlias(int index)
      Gets the alias name of a column.
      Parameters:
      index - the column index
      Returns:
      the column's alias

    • getColumnSuffix

      Optional<String> getColumnSuffix(Backend backend, int index)
      Gets the optional suffix.
      Suffixes usually begin with an underscore.
      Parameters:
      backend - the backend, ignored if !isColumnCountBackendSpecific()
      index - the column index
      Returns:
      the optional suffix

    • getCommentSuffix

      Optional<String> getCommentSuffix(Backend backend, 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:
      backend - the backend, ignored if !isColumnCountBackendSpecific()
      index - the column index
      Returns:
      the optional suffix

    • createColumnNames

      List<String> createColumnNames(Backend backend, String columnName)
      Creates a list of column names.
      Parameters:
      backend - the backend, ignored if !isColumnCountBackendSpecific()
      columnName - the column basename
      Returns:
      the names as an unmodifiable list

    • createColumnNamesAsString

      String createColumnNamesAsString(Backend backend, String columnName, String separator)
      Creates a list of column names as a concatenated string.
      The string can be used in SQL INSERT and UPDATE statements.
      Parameters:
      backend - the backend, ignored if !isColumnCountBackendSpecific()
      columnName - the column basename
      separator - the separator string between names
      Returns:
      the names list

    • isMapNullSupported

      boolean isMapNullSupported()
      Returns whether this type supports mapping null values to some well-defined constant.
      Returns:
      true if mapNull supported

    • getMappedNullValue

      Object getMappedNullValue(Backend backend, int index)
      Gets the mapped non-null value that represents the model's null value.
      The method throws a BackendException, if !isMapNullSupported().
      Parameters:
      backend - the backend, null if not backend-specific
      index - the column index
      Returns:
      the non-null mapped value

    • isUTCSupported

      boolean isUTCSupported()
      Returns whether this type supports the UTC option.
      Returns:
      true if UTC supported

    • isDowncastNecessary

      boolean isDowncastNecessary()
      For certain numeric types, a downcast is 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(Integer index)
      Returns whether this type can be used literally in a query String.
      Parameters:
      index - the column index, null if applies to object of this type
      Returns:
      true if literal String supported, else false

    • toLiteral

      String toLiteral(String str, Integer index)
      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
      index - the column index, null if applies to object of this type
      Returns:
      the SQL literal

    • valueOf

      T valueOf(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

      String valueOfLiteralToCode(String str, Integer index)
      Creates the java code to apply the valueOf method to a String.
      Parameters:
      str - the literal to be parsed
      index - the column index, null if applies to object of this type
      Returns:
      the java code

    • toString

      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

      String getDataTypeConstant()
      Gets the name of the datatype constant.
      Returns:
      the DT_...

    • set

      Object[] set(Backend backend, PreparedStatement statement, int pos, T object, boolean mapNull, Integer size) throws 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:
      SQLException - if failed

    • set

      Object set(Backend backend, PreparedStatement statement, int pos, T object, int index, boolean mapNull, Integer size) throws 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:
      SQLException - if failed

    • get

      T get(Backend backend, ResultSet resultSet, int[] pos, boolean mapNull, Integer size) throws 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:
      SQLException - if failed