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 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

    • 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, 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, Integer scale)
      Gets the column scale.
      Parameters:
      index - the column index
      scale - the scale from the model
      Returns:
      the column scale

    • getColumnValue

      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

      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

      Optional<String> getColumnSuffix(int index)
      Gets the optional suffix.
      Suffixes usually begin with an underscore.
      Parameters:
      index - the column index
      Returns:
      the optional suffix

    • getCommentSuffix

      Optional<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

      String toLiteral(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(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)
      Creates the java code to apply the valueOf method to a String.
      Parameters:
      str - the literal to be parsed
      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