4.2.2.3. Datatype

Datatype interface describes a valid data type for an entity attribute if it is not a reference.

Datatypes are registered in the Datatypes class, which loads and initializes Datatype implementation classes in the following way:

  • Default Datatypes implementations are loaded from the /com/haulmont/chile/core/datatypes/datatypes.xml classpath resource.

  • metadata.xml files from application components and from the project itself are scanned for the datatypes element and if it is found, custom Datatype implementations are loaded. See an example of a custom datatype below.

  • For backward compatibility, the platform searches for the datatypes.xml file in CLASSPATH root, and if it is found, default Datatype implementations are loaded from it instead of the resource mentioned above.

Datatype instance can be obtained in two ways:

  • For an entity attribute – from the corresponding meta-property using getRange().asDatatype() call.

  • Using Datatypes.get() static method by passing to it the name of the Datatype implementation or Java class it was created for.

Datatypes are associated with entity attributes during application start according to the following rules:

  • If @MetaProperty annotation is defined on the field or method having a non-empty datatype value, the attribute is associated with the Datatype instance with the given name.

    For instance, if the entity attribute is declared as in the example below, it will be associated with a custom type – GeoCoordinateDatatype:

    @MetaProperty(datatype = GeoCoordinateDatatype.NAME)
@Column(name = "LATITUDE")
private Double latitude;

  • In most cases, explicit specification is omitted, and the attribute is associated with the Datatype instance from repository, which is returned by Datatypes.get(Class) by supplied field or method type.

    In the example below, latitude attribute will get a standard DoubleDatatype type registered in the /com/haulmont/chile/core/datatypes/datatypes.xml resource:

    @Column(name = "LATITUDE")
private Double latitude;

Basic methods of Datatype interfaces:

  • getName() – returns the unique name of the implementation.

  • format() – converts the passed value into a string.

  • parse() – transforms a string into the value of corresponding type.

Datatype determines two sets of methods for formatting and parsing: considering and not considering locale. Conversion considering locale is applied everywhere in user interface, ignoring locale – in system mechanisms, for example, serialization in REST API.

Parsing formats ignoring locale are specified in the above mentioned datatypes.xml resource or in the datatypes element of the metadata.xml file.

The parsing formats considering locale are provided in the main messages pack, in the strings with the following keys:

  • numberDecimalSeparator – specifies decimal separator for numeric types.

  • numberGroupingSeparator – defines separator between digits groups for numeric types (e.g. when space is used as separator, number will be formatted as 1 000 000).

  • integerFormat – format for Integer and Long types.

  • doubleFormat – format for Double type.

  • decimalFormat – format for `BigDecimal `type.

  • dateTimeFormat – format for java.util.Date type.

  • dateFormat – format for java.sql.Date type.

  • timeFormat – format for java.sql.Time type.

  • trueString – string corresponding to Boolean.TRUE.

  • falseString – string corresponding to Boolean.FALSE.

All the listed formats are specified in the main message pack of CUBA application component by default, and can be overridden in the similar files of the application project.