com.davisor.data
Class TupleData

java.lang.Object
  com.davisor.data.VoidData
      com.davisor.data.VoidValue
          com.davisor.data.GenericValue
              com.davisor.data.TupleData

All Implemented Interfaces:

java.lang.Comparable, Data, DataValue, com.davisor.core.Dupable, java.util.Map, java.io.Serializable, SerializableData

public class TupleData

extends GenericValue

implements java.util.Map

TupleData defines a tuple data structure with elements defined by a tuple data type. TupleData implements DataValue and Map interfaces that allow a number of data manipulation and access operations to be applied on tuple members. Tuple data elements can also be accessed directly with a set of straigforward accessor methods.

TupleData Map interface operations use member identifiers as keys, as defined by tuple data type. The operations are also restricted to tuple member access operations only; any operations that attempt to add or remove elements from the Map will fail, as the underlying tuple structure is fixed, and follows the definition of tuple data type.

Since:

JDK1.1

See Also:

TuplePatternType, TupleType, TupleDataStream, Serialized Form

Nested Class Summary

class	TupleData.TupleEntry TupleEntry implements an entry for TupleData Map interface entrySet method.
class	TupleData.TupleEntryIterator TupleEntryIterator implemens an entry iterator for TupleData Map interface entrySet method.
class	TupleData.TupleEntrySet TupleEntrySet implements an entry set for TupleData Map interface entrySet method.

Nested classes inherited from class java.util.Map

java.util.Map.Entry

Field Summary

static char

DOT Component identity separator ('.').

Fields inherited from class com.davisor.data.VoidData

M_type

Constructor Summary

TupleData(TupleData data, boolean deep)
Deep or shallow copy constructor.

TupleData(TupleType type)
Construct a new tuple data object with the given tuple type.

TupleData(TupleType type, java.sql.ResultSet resultSet)
Construct a new tuple data object from the current result set row.

TupleData(TupleType type, java.lang.String stringValue, java.text.ParsePosition status)
Creates a tuple data value from a string value.

Method Summary

DataValue	abs() Returns absolute data value of current value.
DataValue	add(DataValue value) Adds data values.
DataValue	ceil(DataValue precision) Quantizes the current value up to an even value within given precision.
void	clear() Removes all mappings from this map (not supported).
int	compareTo(java.lang.Object o) Compares this data with other data objects.
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
double	deinterpolate(DataValue min, DataValue max) De-interpolates the current data value to a scalar value, in respect, with the given data value range.
com.davisor.core.Dupable	dup() Makes a deep copy of this object.
java.util.Set	entrySet() Returns a set view of the mappings contained in this map (not supported).
boolean	equals(java.lang.Object o) Tests if this object is equal with another object.
DataValue	floor(DataValue precision) Quantizes the current value to an even value within the given precision.
java.lang.Object	get(java.lang.Object key) Returns the value to which this map maps the specified key.
java.lang.Object	get(java.lang.Object key, java.util.Map additionalValues) Returns the value to which this or an additional map maps the specified key.
java.lang.String	getFormat() Gets the type specification optimal for this particular value.
int	getMaxIndex() Gets the index of the member with the largest value.
int	getMinIndex() Gets the index of the member with the smallest value.
int	getSize() Deprecated. replaced with size which coincides with Map interface.
DataValue	getValue(int index) Gets a direct reference to a tuple member value.
DataValue	getValue(int index, Type type) Gets the tuple member value, optionally converted to the given type.
int	hashCode() Returns a hash code value for the object.
DataValue	interpolate(double value, DataValue max) Interpolates the given scalar value to data value, in respect, with the range defined by this value and the given maximum value.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
boolean	isNull() Tests if this data object value is undetermined.
boolean	isNumber(int index) Tests if the given member is a NumberType instance.
java.util.Set	keySet() Returns a set view of the keys contained in this map.
DataValue	max(DataValue value) Finds the larger of this and the given data value.
DataValue	min(DataValue value) Finds the smallest data value.
DataValue	negate() Returns the negation of current value.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map.
void	putAll(java.util.Map t) Copies all of the mappings from the specified map to this map.
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key from this map if present (not supported).
void	setValue(int index, java.lang.Object value) Sets a tuple member value.
void	setValue(java.lang.String value, java.text.ParsePosition status) Sets data value from a string value.
int	size() Gets the number of tuple elements.
DataValue	sub(DataValue value) Substracts a data value.
java.lang.String	toString() Converts the current tuple data to a string.
DataValue	unit(DataValue targetValue, double maxSteps) Gets the largest suitable unit step to represent a value change between this value and the given target value.
java.util.Collection	values() Returns a collection view of the values contained in this map.

Methods inherited from class com.davisor.data.GenericValue

toStatement, toXML

Methods inherited from class com.davisor.data.VoidValue

div, mul

Methods inherited from class com.davisor.data.VoidData

getDataValue, getType, setType

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.davisor.data.Data

getType

Field Detail

DOT

public static final char DOT

Component identity separator ('.').

See Also:

Constant Field Values

Constructor Detail

TupleData

public TupleData(TupleData data,
                 boolean deep)

Deep or shallow copy constructor. If it is shallow, then the new object shares an underlying type with the original object. If it is deep, then the type is dupped.

Parameters:

data - source data (may be null)

deep - determines if the copying is deep or shallow

See Also:

VoidData.getType(), Type.dup()

TupleData

public TupleData(TupleType type)

Construct a new tuple data object with the given tuple type.

Parameters:

type - tuple type

TupleData

public TupleData(TupleType type,
                 java.sql.ResultSet resultSet)
          throws InvalidDataException,
                 java.sql.SQLException

Construct a new tuple data object from the current result set row.

Parameters:

type - tuple type

resultSet - result set to read data row from

TupleData

public TupleData(TupleType type,
                 java.lang.String stringValue,
                 java.text.ParsePosition status)
          throws InvalidDataException

Creates a tuple data value from a string value.

Parameters:

stringValue - string value to be parsed

status - parse status (may be null)

Throws:

InvalidDataException - if string value could not be parser

See Also:

setValue(String,ParsePosition)

Method Detail

compareTo

public int compareTo(java.lang.Object o)

Compares this data with other data objects.

Specified by:

compareTo in interface java.lang.Comparable

Overrides:

compareTo in class GenericValue

See Also:

GenericValue.max(com.davisor.data.DataValue), GenericValue.min(com.davisor.data.DataValue), Compare.compareTo(Object,Object)

isNull

public boolean isNull()

Tests if this data object value is undetermined.

Specified by:

isNull in interface SerializableData

Overrides:

isNull in class VoidValue

Returns:

always true

abs

public DataValue abs()
              throws InvalidDataException

Returns absolute data value of current value.

Absolute values must satisfy a requirement that when added to any other value, the result must be greater than or equal to the original value.

Specified by:

abs in interface DataValue

Overrides:

abs in class VoidValue

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if absolute value can not be computed

add

public DataValue add(DataValue value)
              throws InvalidDataException

Adds data values.

Specified by:

add in interface DataValue

Overrides:

add in class VoidValue

Parameters:

value - a data value to be added to this data value

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if the data values cannot be added.

ceil

public DataValue ceil(DataValue precision)
               throws InvalidDataException

Quantizes the current value up to an even value within given precision. The returned value is more than or equal with current value, but not more than the current value added by the given precision.

Tuple data values are rounded off by rounding each tuple member separately.

Specified by:

ceil in interface DataValue

Overrides:

ceil in class VoidValue

Parameters:

precision - the precision within the quantization occurs

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if precision was of unacceptable type

See Also:

ceil(com.davisor.data.DataValue)

deinterpolate

public double deinterpolate(DataValue min,
                            DataValue max)
                     throws InvalidDataException

De-interpolates the current data value to a scalar value, in respect, with the given data value range. This gives scalar values between [0,1], when the current data value is within the range, negative scalar values when the data value falls below the range, and scalar values greater than 1.0 otherwise.

Tuple data values are de-interpolated by de-interpolating all tuple members separately. If there are no elements, then the de-interpolation results in a zero value. If there is just one element, then it's de-interpolation value is returned. If there is more than one element, and their respective de-interpolation values are equal, then that particular value is returned. If the values are not equal, then the de-interpolation fails with DeinterpolationException.

Specified by:

deinterpolate in interface DataValue

Overrides:

deinterpolate in class VoidValue

Parameters:

min - a data value representing a range lower limit

max - a data value representing a range higher limit

Returns:

de-interpolated scalar value

Throws:

DeinterpolationException - if the de-interpolation fails due to a de-interpolation value conflict

InvalidDataException - if the de-interpolation fails for some other reason

See Also:

interpolate(double, com.davisor.data.DataValue), DataValue.deinterpolate(com.davisor.data.DataValue, com.davisor.data.DataValue)

floor

public DataValue floor(DataValue precision)
                throws InvalidDataException

Quantizes the current value to an even value within the given precision. The returned value is less than or equal with the current value, but not less than the current value substracted by given precision.

Tuple data values are rounded off by rounding off each tuple member separately.

Specified by:

floor in interface DataValue

Overrides:

floor in class VoidValue

Parameters:

precision - the precision within the quantization occurs

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if precision was of unacceptable type

See Also:

ceil(com.davisor.data.DataValue)

getFormat

public java.lang.String getFormat()

Gets the type specification optimal for this particular value. The specification returned may differ from the current type specification. If so, setting the current type specification equal with the value returned by this method will ensure optimal value formatting and parsing for values of the same magnitude as this value.

Tuple data specification strings are constructed by concatenating paranthesis enclosed tuple member specification strings together.

Specified by:

getFormat in interface DataValue

Overrides:

getFormat in class VoidValue

See Also:

Data.getType(), TupleType.getFormat(), TupleType.setFormat(java.lang.String)

interpolate

public DataValue interpolate(double value,
                             DataValue max)
                      throws InvalidDataException

Interpolates the given scalar value to data value, in respect, with the range defined by this value and the given maximum value. Scalar values between [0,1] result in data values between the current value and the given maximum value. Negative scalar values result in values smaller than this value and scalar values higher than 1.0 return data values above the given maximum.

Tuple data values are interpolated by interpolating all tuple members separately.

Specified by:

interpolate in interface DataValue

Overrides:

interpolate in class VoidValue

Parameters:

value - the scalar value to be interpolated

max - a data value representing a range's higher limit

Returns:

a new data object containing the result

Throws:

InvalidDataException - if interpolation fails

max

public DataValue max(DataValue value)
              throws InvalidDataException

Finds the larger of this and the given data value.

If the given value is null or an instance of VoidValue, a reference to this instance is returned.

Specified by:

max in interface DataValue

Overrides:

max in class GenericValue

Parameters:

value - a data value to be compared to this data value

Returns:

Returns the largest of the compared data values, or a new data value that is larger than or the same as the largest of the compared data values.

Throws:

InvalidDataException - if the data value cannot be compared.

See Also:

GenericValue.compareTo(java.lang.Object)

min

public DataValue min(DataValue value)
              throws InvalidDataException

Finds the smallest data value.

If the given value is null or an instance of VoidValue, a reference to this instance is returned.

Specified by:

min in interface DataValue

Overrides:

min in class GenericValue

Parameters:

value - a data value to be compared with this data value

Returns:

Returns the smallest of the compared data values, or a new data value that is larger than or the same as the largest of the compared data values.

Throws:

InvalidDataException - if the data value cannot be compared.

See Also:

GenericValue.compareTo(java.lang.Object)

negate

public DataValue negate()
                 throws InvalidDataException

Returns the negation of current value.

Specified by:

negate in interface DataValue

Overrides:

negate in class VoidValue

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if absolute value can not be computed

setValue

public void setValue(java.lang.String value,
                     java.text.ParsePosition status)
              throws InvalidDataException

Sets data value from a string value.

The string value is offered to all tuple members, one member at a time. Tuple members are co-operatively responsible of parsing the string and updating the parse position status. If the argument parse position status is null, the parsing starts from the beginning of the given string.

Specified by:

setValue in interface DataValue

Overrides:

setValue in class VoidValue

Parameters:

value - string value to be parsed (may be null)

status - parse status (may be null)

Throws:

InvalidDataException - if string value could not be parser

See Also:

Type.toData(String,ParsePosition)

sub

public DataValue sub(DataValue value)
              throws InvalidDataException

Substracts a data value.

Specified by:

sub in interface DataValue

Overrides:

sub in class VoidValue

Parameters:

value - a data value to be substracted from this data value

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if value can not be substracted.

toString

public java.lang.String toString()

Converts the current tuple data to a string. If a tuple formatter has been set, then the string and tuple members are applied to it and the resulting string is returned. If no tuple specification has been given, then the returned string is a strict concatenation of individual tuple element string representations.

Specified by:

toString in interface DataValue

Overrides:

toString in class VoidData

Returns:

String representation of this data.

See Also:

FormatType.getFormatter(), DataValue.toString()

unit

public DataValue unit(DataValue targetValue,
                      double maxSteps)
               throws InvalidDataException

Gets the largest suitable unit step to represent a value change between this value and the given target value. If the values are equal, the type specific default unit step is returned. If the values are not equal, the given target value must be reached from this value by adding the returned unit step to this value once or more.

The tuple data unit value is computed by taking the unit value for each member separately.

Specified by:

unit in interface DataValue

Overrides:

unit in class VoidValue

Parameters:

targetValue - the target value to be reached (may be null)

maxSteps - maximum number of steps (zero leaves the choise open)

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if target value is unsuitable

dup

public com.davisor.core.Dupable dup()

Makes a deep copy of this object.

Specified by:

dup in interface com.davisor.core.Dupable

Overrides:

dup in class VoidValue

clear

public void clear()

Removes all mappings from this map (not supported).

Specified by:

clear in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map

See Also:

get(java.lang.Object)

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value.

Specified by:

containsValue in interface java.util.Map

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this map (not supported).

Specified by:

entrySet in interface java.util.Map

get

public java.lang.Object get(java.lang.Object key)

Returns the value to which this map maps the specified key.

This implementation is a simplified convenience version of the actual get method. Please see it for full documentation about the various key formats supported.

Specified by:

get in interface java.util.Map

Parameters:

key - element key, as described in get(Object,Map) method documentation

Returns:

value matching given key, or null if no match was found

See Also:

get(Object,Map)

get

public java.lang.Object get(java.lang.Object key,
                            java.util.Map additionalValues)

Returns the value to which this or an additional map maps the specified key.

If the key is an instance of Number, it's integer value is taken as element index, and corresponding element, if any, is returned.

If the key is a list, the first element of the list is extracted and used as a key to retrieve a member value. If the key list then contains more elements, the member found is expected to be another tuple, which is then recursively searched with the remaining list elements.

The key list may also contain just one element, in which case the member value matching that element is returned. If the key list is empty, null is returned. null is also returned if recursive search can not be continued because an intermediate member was not a tuple.

If the key list contains a null element, and an additional values map has been provided, the remaining sublist is used as a key to retrieve a value from the additional values map. If only one key remains in the sublist, the key is taken out of the list before accessing the additional values map, otherwise the whole remaining sublist is used as key. If there is no additional values map, the remaining keys, if any, are ignored, and null is returned. Please note that tuple data objects implement the Map interface, too, so another tuple data object can be directly used as the additional values map.

If the key is an object or integer array, the array elements are treated like keys in a list. In particular, a null object array element will cause a search to be made to the additional values map, if any, with a smaller object array containing the remaining array elements as a key.

If the key was none of the above, it is transformed to a string, and that string is used to search a tuple member with matching identity. If a matching member is found, the value of that member is returned.

If the key string did not match any member identity, it is interpreted as an integer value, if possible, and the corresponding elment, if any, is returned.

If no matching member was found, the key string is interpred as a list of element identities, separated with dot (.) characters. This list is then evaluated just like object lists, with empty list elements corresponding to a null list element.

The following examples list some possibilities of how tuple members can be accessed. Please note in particular, that when working with string keys, member identities take preference over integer and component strings.

• get("a") gets the tuple element with identity "a"
• get("3") gets the element with identity "3", or the 3rd element
• get("a.b") gets the element with identity "a.b", or the "b" element from the "a" tuple member
• get("3.7") gets the element with identity "3.7", or the element "7" from the tuple element "3", or the 7th element from the 3rd element
• get(new Integer(3)) gets the tuple 3rd element
• get(new Integer[] { new Integer(3),new Integer(7)}) gets the 7th element of th 3rd element
• get(new int[] { 3,7 }) gets also the 7th element of th 3rd element
• get(new Object { null,"a","b" }) gets the key 'new Object {"a","b" })' from the additional values map
• get(".a.b") gets the key "a.b" from the additional values map
• get("a..b") gets the key "b" from the additional values map, but only if the principal tuple contains a tuple element "a"

Parameters:

key - element key, as described above

additionalValues - additional values map (may be null, but if not, any access to the map will be synchronized to the map object itself)

Returns:

value matching given key, or null if no match was found

See Also:

containsKey(java.lang.Object), put(java.lang.Object, java.lang.Object), Strings.stringify(Object), TupleType.getIndex(java.lang.String)

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map

keySet

public java.util.Set keySet()

Returns a set view of the keys contained in this map.

Specified by:

keySet in interface java.util.Map

See Also:

TupleType.keySet()

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Associates the specified value with the specified key in this map.

The given key is first transformed to a string, after which a corresponding member identity is searched from current tuple type. If a matching member is found, the given new value will be assigned to that member. returned.

If no matching member is found, but the given object was a Number, it's integer value is taken as element index, and corresponding element, if any is modified.

Specified by:

put in interface java.util.Map

Throws:

java.lang.IllegalArgumentException - if given key does not match any current element, or given value does not match the target element type

See Also:

get(java.lang.Object), setValue(java.lang.String, java.text.ParsePosition), Strings.stringify(Object), TupleType.getIndex(java.lang.String)

putAll

public void putAll(java.util.Map t)

Copies all of the mappings from the specified map to this map.

Specified by:

putAll in interface java.util.Map

See Also:

entrySet(), put(java.lang.Object, java.lang.Object)

remove

public java.lang.Object remove(java.lang.Object key)

Removes the mapping for this key from this map if present (not supported).

Specified by:

remove in interface java.util.Map

equals

public boolean equals(java.lang.Object o)

Tests if this object is equal with another object.

Tuple data objects are equal if their super-classes and members are.

Specified by:

equals in interface java.util.Map

Overrides:

equals in class VoidData

See Also:

Compare.equals(Object,Object)

hashCode

public int hashCode()

Returns a hash code value for the object.

Specified by:

hashCode in interface java.util.Map

Overrides:

hashCode in class VoidData

values

public java.util.Collection values()

Returns a collection view of the values contained in this map.

Specified by:

values in interface java.util.Map

getMaxIndex

public int getMaxIndex()
                throws InvalidDataException

Gets the index of the member with the largest value.

Returns:

index of the member with the largest value, or -1 if there are no members

Throws:

InvalidDataException - if members cannot be compared

See Also:

getValue(int)

getMinIndex

public int getMinIndex()
                throws InvalidDataException

Gets the index of the member with the smallest value.

Returns:

index of the member with the smallest value, or -1 if there are no members

Throws:

InvalidDataException - if members cannot be compared

See Also:

getValue(int)

getSize

public int getSize()

Deprecated. replaced with size which coincides with Map interface.

Gets the number of tuple elements.

See Also:

size()

getValue

public DataValue getValue(int index)

Gets a direct reference to a tuple member value. An invalid index will result in null.

getValue

public DataValue getValue(int index,
                          Type type)

Gets the tuple member value, optionally converted to the given type. An invalid index or value will result in null. A null type will return a direct reference to the requested tuple element.

Parameters:

index - member index

type - the type that the member is to be converted to (may be null)

isNumber

public boolean isNumber(int index)

Tests if the given member is a NumberType instance.

See Also:

TupleType.isNumber(int)

setValue

public void setValue(int index,
                     java.lang.Object value)
              throws InvalidDataException

Sets a tuple member value. If the given value is not a DataValue, or if it's type does not equal the given channel type, the value is converted to target channel type.

If tuple target member type is undefined, and the given value is DataValue, the value is accepted unmodified. If the value is not a DataValue, an InvalidDataException is thrown.

Setting a value to null removes any old value.

Parameters:

index - channel index

value - element value (may be null)

Throws:

InvalidDataException - if value is not valid for the given channel

See Also:

Type.toData(Object)

size

public int size()

Gets the number of tuple elements.

Specified by:

size in interface java.util.Map