org.mmbase.datatypes
Interface DataType<C>

Type Parameters:

C - Class this DataType

All Superinterfaces:

Comparable<DataType<C>>, Descriptor, Serializable

All Known Subinterfaces:

LengthDataType<E>, SequentialDataType<E>

All Known Implementing Classes:

AbstractLengthDataType, BasicDataType, BinaryDataType, BooleanDataType, CheckEqualityDataType, ComparableDataType, ComponentNamesDataType, ConfirmPasswordDataType, DateTimeDataType, DecimalDataType, DoubleDataType, Duration.DataType, FloatDataType, IntegerDataType, LanguageDataType, ListDataType, LongDataType, NodeDataType, NodeManagerNamesDataType, NumberDataType, SecurityContextDataType, Setting.DataType, StringDataType, UniqueStringDataType, UserNodeDataType, WeekdaysDataType, XmlDataType

public interface DataType<C>
extends Descriptor, Comparable<DataType<C>>, Serializable

A value in MMBase (such as the value of a field, or function parameter) is associated with a 'datatype'. A DataType is actually an elaborated wrapper around a Class object, but besides this basic type of the value, it also defines restrictions on the values, a default value, Processors, and perhaps other properties (e.g. properties which describe indications for edit tool implementations). There are several extensions of DataType which normally add other kinds of restrictions which are specific for certain classes of values. All implementations of DataType extend from BasicDataType, but they can sometimes implement different extensions of DataType at the same time ('multiple inheritance').

Since:

MMBase-1.8

Version:

$Id: DataType.java 40242 2009-12-14 15:28:08Z michiel $

Author:

Pierre van Rooden, Michiel Meeuwissen

Nested Class Summary

static interface

DataType.Restriction<D extends Serializable> A restriction controls (one aspect of) the acceptable values of a DataType.

Field Summary

static int	ENFORCE_ABSOLUTE Return value for DataType.Restriction.getEnforceStrength().
static int	ENFORCE_ALWAYS Return value for DataType.Restriction.getEnforceStrength().
static int	ENFORCE_NEVER Return value for DataType.Restriction.getEnforceStrength().
static int	ENFORCE_ONCHANGE Return value for DataType.Restriction.getEnforceStrength().
static int	ENFORCE_ONCREATE Return value for DataType.Restriction.getEnforceStrength().
static int	ENFORCE_ONVALIDATE Return value for DataType.Restriction.getEnforceStrength().
static int	PROCESS_GET
static int	PROCESS_SET
static Collection<LocalizedString>	VALID Returned by validate(Object, Node, Field) if no errors: an empty (nonmodifiable) Collection containing no error messages.
static String	XMLNS The XML Namespace to be used for creating datatype XML

Method Summary

C	cast(Object value, Node node, Field field) Tries to 'cast' an object for use with this parameter.
Collection<LocalizedString>	castAndValidate(Object value, Node node, Field field) Validates a value without knowing its type yet.
Object	castForSearch(Object value, Node node, Field field) Sometimes the the representation of the value is a bit different in the database, or has a different type.
C	castOrException(Object value, Node node, Field field) Tries to 'cast' an object for use with this parameter.
void	checkType(Object value) Checks if the passed object is of the correct class (compatible with the type of this data type), and throws an IllegalArgumentException if it doesn't.
DataType<C>	clone() Returns a cloned instance of this datatype, inheriting all validation rules.
DataType<C>	clone(String name) Returns a cloned instance of this datatype, inheriting all validation rules.
void	finish(Object owner) Lock a dataType so it can be changed or altered.
int	getBaseType() Return the datatype's basic (MMBase) type (i.e., STRING, INTEGER, DATETIME) as definied in the Field interface Note that in some cases (i.e.
String	getBaseTypeIdentifier() Return an identifier for the basic type (i.e., 'string', 'int', 'datetime') supported by this datatype.
CommitProcessor	getCommitProcessor() Return the Commit processor of this datatype
C	getDefaultValue() Returns the default value of this data type.
C	getDefaultValue(Locale locale, Cloud cloud, Field field) Returns the (locale dependent) default value of this data type,
CommitProcessor	getDeleteProcessor() Return the Delete processor of this datatype
int	getEnforceStrength() The maximum enforce strength of all restrictions on this datatype.
LocalizedEntryListFactory<C>	getEnumerationFactory()
DataType.Restriction<LocalizedEntryListFactory<C>>	getEnumerationRestriction() The enumeration for this datatype as a DataType.Restriction.
String	getEnumerationValue(Locale locale, Cloud cloud, Node node, Field field, Object key) Returns a (gui) value from a list of restricted enumerated values, or null if no enumeration restrictions apply or the value cannot be found.
Iterator<Map.Entry<C,String>>	getEnumerationValues(Locale locale, Cloud cloud, Node node, Field field) Returns an iterator over all possible values for this datatype, as Map.Entrys, or null if no enumeration restrictions apply.
Handler<?>	getHandler(String mimeType) Returns a handler for given mimetype for this DataType.
Map<String,Handler<?>>	getHandlers()
DataType<?>	getOrigin() Return the DataType from which this one inherited, or null
Processor	getProcessor(int action) Returns the default processor for this action
Processor	getProcessor(int action, int processingType) Returns the processor for this action and processing type
DataType.Restriction<Boolean>	getRequiredRestriction() Returns the 'required' restriction, containing the value, error messages, and fixed status of this attribute.
String[]	getStyleClasses()
Class<C>	getTypeAsClass() Returns the type of values that this data type accepts.
DataType.Restriction<Boolean>	getUniqueRestriction() Returns the 'unique' restriction, containing the value, error messages, and fixed status of this attribute.
boolean	isFinished() Is datatype locked
boolean	isRequired() Returns whether this field is required (may not be null, or otherwise empty).
boolean	isUnique() Returns whether this field has a unique restriction.
<D> D	preCast(D value, Node node, Field field) Before actually 'cast' an object to the right type, it may undergo some conversion by the datatype, e.g.
DataType<C>	rewrite(Object owner) Unlock a DataType so it can be changed or altered.
void	setCommitProcessor(CommitProcessor cp) Set the Commit processor of this datatype
void	setDefaultValue(Object def) Set the default value for this DataType
void	setProcessor(int action, Processor processor) Sets the processor for this action
void	setProcessor(int action, Processor processor, int processingType) Sets the processor for this action
void	setRequired(boolean required) Sets whether the data type requires a value, which means that it may not remain unfilled.
void	setUnique(boolean unique) Sets whether the data type requires a value.
Element	toXml() Returns a DOM element describing this DataType.
void	toXml(Element element) Fills this datatype in another XML (for example in the xml of getOrigin(), to make one XML, fully describing the DataType).
Collection<LocalizedString>	validate(C value)
Collection<LocalizedString>	validate(C value, Node node, Field field) Checks if the passed object obeys the restrictions defined for this type.

Methods inherited from interface org.mmbase.bridge.Descriptor

getDescription, getDescription, getGUIName, getGUIName, getLocalizedDescription, getLocalizedGUIName, getName, setDescription, setDescription, setGUIName, setGUIName

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

XMLNS

static final String XMLNS

The XML Namespace to be used for creating datatype XML

See Also:

Constant Field Values

PROCESS_GET

static final int PROCESS_GET

See Also:

Constant Field Values

PROCESS_SET

static final int PROCESS_SET

See Also:

Constant Field Values

ENFORCE_ABSOLUTE

static final int ENFORCE_ABSOLUTE

Return value for DataType.Restriction.getEnforceStrength(). This means that the value restriction must be enforced always, and furthermore, that extensions (based on clone) cannot loosen it. For example, the absolute maximum for any datatype backed by a integer is Integer.MAX_VALUE, there is no way you can even store a bigger value in this, so this restriction is 'absolute'.

See Also:

Constant Field Values

ENFORCE_ALWAYS

static final int ENFORCE_ALWAYS

Return value for DataType.Restriction.getEnforceStrength(). This means that a restriction on a value must be enforced always.

See Also:

Constant Field Values

ENFORCE_ONCHANGE

static final int ENFORCE_ONCHANGE

Return value for DataType.Restriction.getEnforceStrength(). This means that a restriction on a value must be enforced only if it was changed.

See Also:

Constant Field Values

ENFORCE_ONCREATE

static final int ENFORCE_ONCREATE

Return value for DataType.Restriction.getEnforceStrength(). This means that ta restriction on a value must be enforced only on creation.

See Also:

Constant Field Values

ENFORCE_ONVALIDATE

static final int ENFORCE_ONVALIDATE

Return value for DataType.Restriction.getEnforceStrength(). This means that the restriction on a value must be enforced only on validation of the value. This means that it has no influence of the validity of the node.

Since:

MMBase-1.9.1

See Also:

Constant Field Values

To Do:

No difference made between always/change/create for this. We could also add ENfORCE_ONVALIDATE_CHANGE, ENFORMCE_ONVALIDATE_CREATE

ENFORCE_NEVER

static final int ENFORCE_NEVER

Return value for DataType.Restriction.getEnforceStrength(). This means that the restriction on a value must be enforced never, so the restriction serves only as UI indication.

See Also:

Constant Field Values

VALID

static final Collection<LocalizedString> VALID

Returned by validate(Object, Node, Field) if no errors: an empty (nonmodifiable) Collection containing no error messages.

Method Detail

getOrigin

DataType<?> getOrigin()

Return the DataType from which this one inherited, or null

Returns:

inherited DataType

getBaseTypeIdentifier

String getBaseTypeIdentifier()

Return an identifier for the basic type (i.e., 'string', 'int', 'datetime') supported by this datatype.

Returns:

identifier for the basic type

getBaseType

int getBaseType()

Return the datatype's basic (MMBase) type (i.e., STRING, INTEGER, DATETIME) as definied in the Field interface Note that in some cases (i.e. with older clouds) this may differ from the basic type of the datatype's field, which defines in what format the data is stored.

Returns:

identifier of the basic type

See Also:

Field.getType()

getTypeAsClass

Class<C> getTypeAsClass()

Returns the type of values that this data type accepts.

Returns:

the type as a Class

checkType

void checkType(Object value)

Checks if the passed object is of the correct class (compatible with the type of this data type), and throws an IllegalArgumentException if it doesn't.

Parameters:

value - the value whose type (class) to check

Throws:

IllegalArgumentException - if the type is not compatible

cast

C cast(Object value,
       Node node,
       Field field)

Tries to 'cast' an object for use with this parameter. E.g. if value is a String, but this parameter is of type Integer, then the string can be parsed to Integer.

Parameters:

value - The value to be filled in a value with this DataType.

node - Sometimes a node might be needed.

field - Sometimes a (or 'the') field might be needed.

Returns:

casted object of Class of this DataType

castOrException

C castOrException(Object value,
                  Node node,
                  Field field)
                  throws CastException

Tries to 'cast' an object for use with this parameter. E.g. if value is a String, but this parameter is of type Integer, then the string can be parsed to Integer. This method may thow CastException if such casting is not feasible. E.g. most strings cannot be reasonably casted to numbers. The method cast(java.lang.Object, org.mmbase.bridge.Node, org.mmbase.bridge.Field) will return -1. This one will trow exception.

Parameters:

value - The value to be filled in a value with this DataType.

node - Sometimes a node might be needed.

field - Sometimes a (or 'the') field might be needed.

Returns:

casted object of Class of this DataType

Throws:

ClassException

CastException

Since:

MMBase-2.0

preCast

<D> D preCast(D value,
              Node node,
              Field field)

Before actually 'cast' an object to the right type, it may undergo some conversion by the datatype, e.g. enumerations may get resolved (enumerations have the feature that they can e.g. resolve java-constants to their values). This does not guarantee that the value has the 'proper' type, but only that it now can be cast to the right type without further problems. (Casting.toType(Class, Object) should do). preCast should not change the actual type of value. It is e.g. used in the Node#setStringValue, and the processor may expect a String there.

Type Parameters:

D -

Parameters:

value - The value to be filled in a value with this DataType.

node - Sometimes a node might be needed.

field - Sometimes a (or 'the') field might be needed.

Returns:

converted value to be able to cast to the DataType of the field

castForSearch

Object castForSearch(Object value,
                     Node node,
                     Field field)

Sometimes the the representation of the value is a bit different in the database, or has a different type. So when constraining a search on the value, casting is done by this. This may default to cast(Object, Node, Field).

Since:

MMBase-1.9.1

getDefaultValue

C getDefaultValue()

Returns the default value of this data type.

Returns:

the default value

getDefaultValue

C getDefaultValue(Locale locale,
                  Cloud cloud,
                  Field field)

Returns the (locale dependent) default value of this data type,

Since:

MMBase-1.8.6

setDefaultValue

void setDefaultValue(Object def)

Set the default value for this DataType

Parameters:

def - default value

rewrite

DataType<C> rewrite(Object owner)

Unlock a DataType so it can be changed or altered.

Parameters:

owner - the object to finish datatypes with

Returns:

unlocked DataType

isFinished

boolean isFinished()

Is datatype locked

Returns:

true when datatype is locked

finish

void finish(Object owner)

Lock a dataType so it can be changed or altered.

Parameters:

owner - the object to finish datatypes with

getEnforceStrength

int getEnforceStrength()

The maximum enforce strength of all restrictions on this datatype. See ENFORCE_ALWAYS, ENFORCE_ONCHANGE, ENFORCE_NEVER.

Returns:

maximum enforce strength

validate

Collection<LocalizedString> validate(C value)

Parameters:

value - the value to be validated

Returns:

The error message(s) if the value is not compatible. An empty collection if valid.

See Also:

validate(Object, Node, Field)

validate

Collection<LocalizedString> validate(C value,
                                     Node node,
                                     Field field)

Checks if the passed object obeys the restrictions defined for this type.

Parameters:

value - the value to validate

node - the node for which the datatype is checked. If not null, and the datatype is determined as unique, than uniquness is checked for this value using the passed field.

field - the field for which the datatype is checked.

Returns:

The error message(s) if the value is not compatible. An empty collection (VALID)if the value is valid.

castAndValidate

Collection<LocalizedString> castAndValidate(Object value,
                                            Node node,
                                            Field field)

Validates a value without knowing its type yet.

Since:

MMBase-1.9.1

isRequired

boolean isRequired()

Returns whether this field is required (may not be null, or otherwise empty).

Returns:

true if the field is required

getRequiredRestriction

DataType.Restriction<Boolean> getRequiredRestriction()

Returns the 'required' restriction, containing the value, error messages, and fixed status of this attribute.

Returns:

the restriction as a DataType.Restriction

setRequired

void setRequired(boolean required)

Sets whether the data type requires a value, which means that it may not remain unfilled.

Parameters:

required - true if a value is required

Throws:

IllegalStateException - if the datatype was finished (and thus can no longer be changed)

isUnique

boolean isUnique()

Returns whether this field has a unique restriction. Uniqueness is generally achieved through association of the datatype with one or more sets of fields. This is notably different from other datatype properties. Note that the MMBase core does not generally enforce uniqueness, but the storage layer might.

Returns:

true if the field is unique

getUniqueRestriction

DataType.Restriction<Boolean> getUniqueRestriction()

Returns the 'unique' restriction, containing the value, error messages, and fixed status of this attribute.

Returns:

the restriction as a DataType.Restriction

setUnique

void setUnique(boolean unique)

Sets whether the data type requires a value.

Parameters:

unique - true if a value is unique

Throws:

IllegalStateException - if the datatype was finished (and thus can no longer be changed)

getEnumerationValues

Iterator<Map.Entry<C,String>> getEnumerationValues(Locale locale,
                                                   Cloud cloud,
                                                   Node node,
                                                   Field field)

Returns an iterator over all possible values for this datatype, as Map.Entrys, or null if no enumeration restrictions apply. Every Map entry contains as key the 'value' for this datatype and as value it contains the description for this value in the given locale. This Iterator skips all entries which are impossible because of other restrictions on this datatype.

Parameters:

locale - for which to produce

cloud - Possibly the possible values depend on a cloud (security)

node - Possibly the possible values depend on an actual node (this may be, and in the default implementation is, ignored)

field - Possibly the possible values depend on an actual field (this may be, and in the default implementation is, ignored)

Returns:

iterator over all possible values for this datatype

getEnumerationValue

String getEnumerationValue(Locale locale,
                           Cloud cloud,
                           Node node,
                           Field field,
                           Object key)

Returns a (gui) value from a list of restricted enumerated values, or null if no enumeration restrictions apply or the value cannot be found.

Parameters:

locale - for which to produce

cloud - Possibly the possible values depend on a cloud (security)

node - Possibly the possible values depend on an actual node (this may be, and in the default implementation is, ignored)

field - Possibly the possible values depend on an actual field (this may be, and in the default implementation is, ignored)

key - the key for which to look up the (gui) value

Returns:

a (gui) value from a list of restricted enumerated values

getEnumerationFactory

LocalizedEntryListFactory<C> getEnumerationFactory()

Returns:

the LocalizedEntryListFactory which will be used to produce the result of getEnumerationValues(java.util.Locale, org.mmbase.bridge.Cloud, org.mmbase.bridge.Node, org.mmbase.bridge.Field). Never null. This can be used to add more possible values.

getEnumerationRestriction

DataType.Restriction<LocalizedEntryListFactory<C>> getEnumerationRestriction()

The enumeration for this datatype as a DataType.Restriction.

Returns:

enumeration for this datatype

getCommitProcessor

CommitProcessor getCommitProcessor()

Return the Commit processor of this datatype

Returns:

Commit processor

setCommitProcessor

void setCommitProcessor(CommitProcessor cp)

Set the Commit processor of this datatype

Parameters:

cp - Commit processor

getDeleteProcessor

CommitProcessor getDeleteProcessor()

Return the Delete processor of this datatype

Returns:

A commitprocessor that will be called if the Node is deleted.

Since:

MMBase-1.9.1

getProcessor

Processor getProcessor(int action)

Returns the default processor for this action

Parameters:

action - either PROCESS_GET, or PROCESS_SET XXX What exactly would be against getGetProcesor(), getSetProcessor() ?

Returns:

the default processor for this action

getProcessor

Processor getProcessor(int action,
                       int processingType)

Returns the processor for this action and processing type

Parameters:

action - either PROCESS_GET, or PROCESS_SET

processingType - the MMBase type defining the type of value to process

Returns:

the processor for this action and processing type

setProcessor

void setProcessor(int action,
                  Processor processor)

Sets the processor for this action

Parameters:

action - either PROCESS_GET, or PROCESS_SET

processor - the processor for this action

setProcessor

void setProcessor(int action,
                  Processor processor,
                  int processingType)

Sets the processor for this action

Parameters:

action - either PROCESS_GET, or PROCESS_SET

processor - the processor for this action and processing type

processingType - the MMBase type defining the type of value to process

clone

DataType<C> clone()

Returns a cloned instance of this datatype, inheriting all validation rules. Unlike the original datatype though, the cloned copy is declared unfinished even if the original was finished. This means that the cloned datatype can be changed.

Returns:

cloned instance

clone

DataType<C> clone(String name)

Returns a cloned instance of this datatype, inheriting all validation rules. Similar to calling clone(), but changes the data type name if one is provided.

Parameters:

name - the new name of the copied datatype (can be null, in which case the name is not changed).

Returns:

cloned DataType

toXml

Element toXml()

Returns a DOM element describing this DataType.

Returns:

a DOM element describing this DataType.

To Do:

EXPERIMENTAL.

toXml

void toXml(Element element)

Fills this datatype in another XML (for example in the xml of getOrigin(), to make one XML, fully describing the DataType). The implementation of this method is unfinished!

Parameters:

element - a 'datatype' element.

To Do:

EXPERIMENTAL

getHandler

Handler<?> getHandler(String mimeType)

Returns a handler for given mimetype for this DataType. The handler can be used to produce UI for values of this datatype.

Since:

MMBase-1.9.1

To Do:

EXPERIMENTAL

getHandlers

Map<String,Handler<?>> getHandlers()

Since:

MMBase-1.9.1

getStyleClasses

String[] getStyleClasses()

Since:

MMBase-1.9.1