org.mmbase.datatypes
Interface DataType

All Superinterfaces:

Cloneable, Comparable, Descriptor, Serializable

All Known Subinterfaces:

LengthDataType

All Known Implementing Classes:

AbstractLengthDataType, BasicDataType, StringDataType

public interface DataType

extends Descriptor, Cloneable, Comparable, 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 arround 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,v 1.52 2006/04/29 19:41:09 michiel Exp $

Author:

Pierre van Rooden, Michiel Meeuwissen

Nested Class Summary

static interface

DataType.Restriction 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	PROCESS_GET
static int	PROCESS_SET
static Collection	VALID Returned by validate(java.lang.Object) if no errors: an empty (nonmodifiable) Collection.
static String	XMLNS The XML Namespace to be used for creating datatype XML

Method Summary

Object	cast(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.
Object	clone() Returns a cloned instance of this datatype, inheriting all validation rules.
Object	clone(String name) Returns a cloned instance of this datatype, inheriting all validation rules.
void	finish(Object owner)
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()
Object	getDefaultValue() Returns the default value of this data type.
LocalizedEntryListFactory	getEnumerationFactory()
DataType.Restriction	getEnumerationRestriction() The enumeration for this datatype as a DataType.Restriction.
Object	getEnumerationValue(Locale locale, Cloud cloud, Node node, Field field, Object key) Returns a (gui) value from a list of retsricted enumerated values, or null if no enumeration restrictions apply or teh value cannot be found.
Iterator	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.
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	getRequiredRestriction() Returns the 'required' restriction, containing the value, errormessages, and fixed status of this attribute.
Class	getTypeAsClass() Returns the type of values that this data type accepts.
DataType.Restriction	getUniqueRestriction() Returns the 'unique' restriction, containing the value, error messages, and fixed status of this attribute.
void	inherit(BasicDataType origin) Inherit properties and processors from the passed datatype.
boolean	isFinished()
boolean	isRequired() Returns whether this field is required (should have content).
boolean	isUnique() Returns whether this field has a unique restriction.
Object	preCast(Object 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	rewrite(Object owner)
void	setCommitProcessor(CommitProcessor cp)
void	setDefaultValue(Object def)
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	validate(Object value)
Collection	validate(Object 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

public static final String XMLNS

The XML Namespace to be used for creating datatype XML

See Also:

Constant Field Values

PROCESS_GET

public static final int PROCESS_GET

See Also:

Constant Field Values

PROCESS_SET

public static final int PROCESS_SET

See Also:

Constant Field Values

ENFORCE_ABSOLUTE

public static final int ENFORCE_ABSOLUTE

Return value for DataType.Restriction.getEnforceStrength(). This means that the value 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

public static final int ENFORCE_ALWAYS

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

See Also:

Constant Field Values

ENFORCE_ONCHANGE

public static final int ENFORCE_ONCHANGE

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

See Also:

Constant Field Values

ENFORCE_ONCREATE

public static final int ENFORCE_ONCREATE

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

See Also:

Constant Field Values

ENFORCE_NEVER

public static final int ENFORCE_NEVER

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

See Also:

Constant Field Values

VALID

public static final Collection VALID

Returned by validate(java.lang.Object) if no errors: an empty (nonmodifiable) Collection.

Method Detail

inherit

public void inherit(BasicDataType origin)

Inherit properties and processors from the passed datatype.

getOrigin

public DataType getOrigin()

Return the DataType from which this one inherited, or null

getBaseTypeIdentifier

public String getBaseTypeIdentifier()

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

getBaseType

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

See Also:

Field.#getType

getTypeAsClass

public Class getTypeAsClass()

Returns the type of values that this data type accepts.

Returns:

the type as a Class

checkType

public 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

public Object 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.

preCast

public Object preCast(Object 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 garantuee that the value has the 'proper' type, but only that it now can be casted to the right type without further problems. (Casting.toType(java.lang.Class, java.lang.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.

getDefaultValue

public Object getDefaultValue()

Returns the default value of this data type.

Returns:

the default value

setDefaultValue

public void setDefaultValue(Object def)

Warning: No Java Documentation Available.

rewrite

public DataType rewrite(Object owner)

Warning: No Java Documentation Available.

isFinished

public boolean isFinished()

Warning: No Java Documentation Available.

finish

public void finish(Object owner)

Warning: No Java Documentation Available.

validate

public Collection validate(Object 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

public Collection validate(Object 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 if the value is valid.

isRequired

public boolean isRequired()

Returns whether this field is required (should have content). Note that the MMBase core does not generally enforce required fields to be filled - If not provided, a default value (generally an empty string or the integer value -1) is filled in by the system.

Returns:

true if the field is required

getRequiredRestriction

public DataType.Restriction getRequiredRestriction()

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

Returns:

the restriction as a DataType.Restriction

setRequired

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

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

isUnique

public 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

public DataType.Restriction getUniqueRestriction()

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

Returns:

the restriction as a DataType.Restriction

setUnique

public void setUnique(boolean unique)

Sets whether the data type requires a value.

Parameters:

unique - true if a value is unique

Throws:

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

getEnumerationValues

public Iterator 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)

getEnumerationValue

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

Returns a (gui) value from a list of retsricted enumerated values, or null if no enumeration restrictions apply or teh 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

getEnumerationFactory

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

public DataType.Restriction getEnumerationRestriction()

The enumeration for this datatype as a DataType.Restriction.

getCommitProcessor

public CommitProcessor getCommitProcessor()

Warning: No Java Documentation Available.

setCommitProcessor

public void setCommitProcessor(CommitProcessor cp)

Warning: No Java Documentation Available.

getProcessor

public 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() ?

getProcessor

public 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

setProcessor

public void setProcessor(int action,
                         Processor processor)

Sets the processor for this action

Parameters:

action - either PROCESS_GET, or PROCESS_SET

setProcessor

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

Sets the processor for this action

Parameters:

action - either PROCESS_GET, or PROCESS_SET

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

clone

public Object 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.

clone

public Object 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).

toXml

public Element toXml()

Returns a DOM element describing this DataType.

toXml

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