net.sf.mmm.util.lang.api

Interface Datatype

All Superinterfaces:

Serializable

All Known Subinterfaces:

EntityId, EnumDefinition<TYPE,CATEGORY>, EnumType<V>, EnumTypeWithCategory<V,CATEGORY>, SimpleDatatype<V>, VersionIdentifier

All Known Implementing Classes:

AbstractDatatype, AbstractEntityId, AbstractEnumDefinition, AbstractSimpleDatatype, AbstractSimpleDatatypeBase, AbstractSimpleEnumDefinition, AbstractVersionIdentifier, Alignment, BooleanEnum, BooleanEnumDefinition, Comparator, CompareOperator, Conjunction, DevelopmentPhase, DiacriticalMark, Direction, EntityIdImpl, EnumEnumDefinition, EnumEnumType, HorizontalAlignment, Orientation, Password, SortOrder, VersionIdentifierImpl, VerticalAlignment

public interface Datatype
extends Serializable

This is the interface for a datatype. A datatype is an object representing a value of a specific type with the following aspects:

• It has a technical or business specific semantic.
• Its JavaDoc explains the meaning and semantic of the value.
• It is immutable and therefore stateless (its value assigned at construction time and can not be modified).
• It is Serializable.
• It implements equals and hashCode properly (two different instances with the same value are equal and have the same hash).
• It shall ensure syntactical validation so it is NOT possible to create an instance with an invalid value.
• It is responsible for formatting its value to a string representation suitable for sinks such as UI, loggers, etc. Also consider cases like a Datatype representing a password where toString() should return something like "********" instead of the actual password to prevent security accidents.
• It is responsible for parsing the value from other representations such as a string (as needed).
• It shall provide required logical operations on the value to prevent redundancies. Due to the immutable attribute all manipulative operations have to return a new Datatype instance (see e.g. BigDecimal.add(java.math.BigDecimal)).
• It should implement Comparable if a natural order is defined.

Based on the Datatype a presentation layer can decide how to view and how to edit the value. Therefore a structured data model should make use of custom datatypes in order to be expressive.
Common generic datatypes are String, Boolean, Number and its subclasses, Currency, etc. They should always be accepted and supported as datatypes (even though they obviously do NOT implement this interface).
Please note that both Date and Calendar are mutable and have very confusing APIs. Therefore, use JSR-310 or jodatime instead.
Even if a datatype is technically nothing but a String or a Number but logically something special it is worth to define it as a dedicated datatype class already for the purpose of having a central javadoc to explain it. On the other side avoid to introduce technical datatypes like String32 for a String with a maximum length of 32 characters as this is not adding value in the sense of a real Datatype.
An implementation of this interface should usually declare its Fields as final to ensure being immutable. However, we are supporting Google Web Toolkit (GWT) that has additional requirements for serialization:

• Fields are NOT final. See GWT issue 1054.
• It has a protected non-arg Constructor.

It is suitable and in most cases also recommended to use the class implementing the datatype as API omitting a dedicated interface.

Since:

2.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

AbstractSimpleDatatype

Method Summary

Modifier and Type	Method and Description
String	toString() Returns the official String representation of this Datatype.

Method Detail

toString

String toString()

Returns the official String representation of this Datatype. While the general contract of Object.toString() is very weak and mainly used for debugging, the contract here is very strong. The returned String has to be suitable for end-users and official output to any kind of sink.
ATTENTION:
This method is not supposed to do internationalization (I18N). See NlsMessage for this purpose and implement NlsObject if you want to support I18N/L10N.

Overrides:

toString in class Object

Returns:

the official String representation to display the value of this Datatype.