ch.agent.crnickl.api

Interface ValueType<T>

Type Parameters:

T - the underlying data type of the values

All Superinterfaces:

DBObject

All Known Subinterfaces:

UpdatableValueType<T>

All Known Implementing Classes:

UpdatableValueTypeImpl, ValueTypeImpl

public interface ValueType<T>
extends DBObject

A ValueType defines value domains for Attributes and Series. Value types can be provided by the system or can be defined procedurally with a ValueScanner.

Author:

Jean-Paul Vetterli

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ValueType.StandardValueType StandardValueType provides an easy way to identify built-in value types.

Method Summary

Modifier and Type	Method and Description
void	check(T value) Check that the value is allowed.
UpdatableValueType<T>	edit() Return an UpdatableValueType corresponding to this value type.
String	getExternalRepresentation() Return a string providing an external representation of the value type.
String	getName() Return the name of the value type.
ValueScanner<T>	getScanner() Return the value scanner.
ValueType.StandardValueType	getStandardValueType() Return the constant representing the value type when it is a built-in value type.
Class<T>	getType() Return the class of the underlying data type.
Map<T,String>	getValueDescriptions() Return a map with allowed values as keys and a description for each value.
Set<T>	getValues() Return the set of allowed values.
Collection<String>	getValues(String format) Return values and descriptions as a collection of formatted strings.
boolean	isBuiltIn() Deprecated.
boolean	isCompatible(Object obj) Returns true if the object can be assigned to a variable of the underlying data type.
boolean	isRestricted() Return true if the value type maintains an exhaustive list of allowed values.
T	scan(String value) Convert the argument to an object of the underlying data type.
String	toString(Object value) Convert the argument to a string.
<S> ValueType<S>	typeCheck(Class<S> type) Cast the value type to the type specified.

Methods inherited from interface ch.agent.crnickl.api.DBObject

getDatabase, getId, getSurrogate, inConstruction, isValid

Method Detail

getName

String getName()

Return the name of the value type.

Returns:

the name of the value type

isRestricted

boolean isRestricted()

Return true if the value type maintains an exhaustive list of allowed values.

Returns:

true if the value type has a list of allowed values

isBuiltIn

@Deprecated
boolean isBuiltIn()

Deprecated.

This method is obsolete and always return false.

Returns:

false

getType

Class<T> getType()

Return the class of the underlying data type.

Returns:

the class of the underlying data type

getScanner

ValueScanner<T> getScanner()

Return the value scanner.

Returns:

the value scanner

getStandardValueType

ValueType.StandardValueType getStandardValueType()

Return the constant representing the value type when it is a built-in value type. Return null if the value type is not built-in.

Returns:

the constant representing the value type or null

getExternalRepresentation

String getExternalRepresentation()

Return a string providing an external representation of the value type. This is either the string value of the standard value type or the name of the value scanner class.

Returns:

the external representation of the value type

getValues

Set<T> getValues()

Return the set of allowed values. Returns an empty set when there is no restriction.

Returns:

the set of allowed values

Throws:

T2DBException

getValueDescriptions

Map<T,String> getValueDescriptions()

Return a map with allowed values as keys and a description for each value. Descriptions can be null. Returns an empty map when values are not restricted.

Returns:

a map with values and their descriptions

Throws:

T2DBException

getValues

Collection<String> getValues(String format)

Return values and descriptions as a collection of formatted strings. If a value has no description, simply convert it to a string. If a value has a description, use the format parameter, which is expected to include two %s fields. If the format is null, use a built-in format.

Parameters:

format - a format

Returns:

a collection of formatter values and descriptions

scan

T scan(String value)
throws T2DBException

Convert the argument to an object of the underlying data type. Throw an exception if the argument cannot be converted. A null is converted to a null. An empty value is converted to a null, unless the value type is restricted. When the value type is restricted, it must be capable of scanning and converting the empty string, and the result of the conversion must be present in the set of allowed values.

Parameters:

value - a string

Returns:

the value converted to the value type's underlying data type

Throws:

T2DBException

isCompatible

boolean isCompatible(Object obj)

Returns true if the object can be assigned to a variable of the underlying data type. The method is provided because the instanceof operator cannot be used with generics. The method does not check if the value is allowed. Use check(T) for that.

Parameters:

obj - an object

Returns:

true if the object can be assigned to a variable of the underlying data type

check

void check(T value)
    throws T2DBException

Check that the value is allowed. Throw an exception if a set of allowed values is defined and the value is not in the set.

Parameters:

value - a value

Throws:

T2DBException

toString

String toString(Object value)
         throws T2DBException

Convert the argument to a string. An exception is thrown if the value is illegal for the value type. For example if the scanner actual type is Integer, and the scanner requires positive numbers, a negative or zero value will result in an exception. With most scanners, a null value is converted to a null result.

Parameters:

value - a value

Returns:

the value converted to a string

Throws:

T2DBException

edit

UpdatableValueType<T> edit()

Return an UpdatableValueType corresponding to this value type. Successfully getting an Updatable object does not imply that updates can be successfully applied.

Returns:

an updatable value type corresponding to this value type

typeCheck

<S> ValueType<S> typeCheck(Class<S> type)
                    throws T2DBException

Cast the value type to the type specified. The method performs type checking at run time and allows to catch type errors in controlled fashion.

Parameters:

type - the underlying type required

Returns:

the value type cast to the type specified

Throws:

T2DBException