mondrian.util
Interface SpatialValueTree<K,E,V>

Type Parameters:

K - Type of the dimensions.

E - Type of the dimension bounds.

V - Type of the values to store.

public interface SpatialValueTree<K,E,V>

A SpatialValueTree is a multidimensional index of values. The data is organized in a fixed number of dimensions, each of which contain a fixed number of nodes. The node of an axis is called a bound. Each node might contain X number of values.

You can think of a SpatialValueTree as a multi dimensional list where collections of values are stored in each possible tuple.

When performing operations on the tree, such as adding values or retrieving them, we use a SpatialValueTree.SpatialRegion. Each region can cover more than one bound per dimension.

When evaluating a region, if a dimension is omitted form a region, this means that the region doesn't overlap the dimension at all. It is not the same as covering all the values of the dimension axis.

Example. A tree of years and states containing a X values per leaf node would look something like this:

year:1997
state:NY
value:0x000423
state:FL
value:0x000236
value:0x000423
year:1998
state:NY
value:[EMPTY]
state:FL
value:0x000501

A region key consists of a list of dimensions included in the region along with an array of bounds for each of these dimensions. The boundaries of a given region along a given dimension axis is specified by an array of objects. All of these objects must be nodes of the specified dimension for a region to be valid within a tree context. As an example, the following key:

[ {'year', [1997]}, {'state', ['FL']} ]

... would return { [0x000236] [0x000423] }.

The region keys can have more than one predicate value per axis. If we use the same tree as above, and we query it using the following region key:

[ {'year', [1997]}, {'state', ['NY','FL']} ]

... would return { [0x000236] [0x000423] }.

The region key also supports wildcard values. If you want to represent all of the values of a given axis, you can put a single reference to SpatialValueTree#AXIS_WILDCARD.

[ {'year', [AXIS_WILDCARD]}, {'state', ['NY','FL']} ]

... would return { [0x000236] [0x000423] [0x000501] }.

By convention, implementations are required to compare all generic types using Object.hashCode() and Object.equals(Object). Users of this class should also use generic types which implement Object.hashCode() and Object.equals(Object) to avoid performance and consistency issues.

Nested Class Summary

static interface

SpatialValueTree.SpatialRegion<K,E> Describes a spatial region within a SpatialValueTree.

Field Summary

static Object

AXIS_WILDCARD Used as a token to represent all the values of an axis.

Method Summary

void	add(SpatialValueTree.SpatialRegion<K,E> regionkey, V value) Stores a string value at all points which intersect with the passed region key.
void	clear(SpatialValueTree.SpatialRegion<K,E> regionKey) Clears all the values found at the provided region key.
Set<V>	get(SpatialValueTree.SpatialRegion<K,E> regionKey) Looks up all the values registered in nodes intersecting with the provided region key.
int	getDimensionality() Tells the number of dimensions in this tree.
List<K>	getDimensions() Returns a list of all the dimensions present in this tree.
Set<V>	match(SpatialValueTree.SpatialRegion<K,E> regionKey) Looks up all the values registered in nodes intersecting with the provided region key.

Field Detail

AXIS_WILDCARD

static final Object AXIS_WILDCARD

Used as a token to represent all the values of an axis. Overrides Object.equals(Object) and Object.hashCode() so that only identity comparison are used.

Method Detail

add

void add(SpatialValueTree.SpatialRegion<K,E> regionkey,
         V value)

Stores a string value at all points which intersect with the passed region key.

clear

void clear(SpatialValueTree.SpatialRegion<K,E> regionKey)

Clears all the values found at the provided region key.

Parameters:

regionKey - The region key of the values to clear.

get

Set<V> get(SpatialValueTree.SpatialRegion<K,E> regionKey)

Looks up all the values registered in nodes intersecting with the provided region key.

Parameters:

regionKey - The region key inside of which to search for value nodes.

Returns:

An unordered set of all the unique values intersecting with the region.

match

Set<V> match(SpatialValueTree.SpatialRegion<K,E> regionKey)

Looks up all the values registered in nodes intersecting with the provided region key. If a value is present in all of the nodes, a unique set of all the values found will be returned. An empty set is returned if no complete match could be found.

Parameters:

regionKey - The region key inside of which to search for value nodes.

Returns:

An unordered set of all the unique values intersecting with the region and covering it entirely, or an empty set otherwise.

getDimensions

List<K> getDimensions()

Returns a list of all the dimensions present in this tree.

Returns:

A list of dimension unique ids.

getDimensionality

int getDimensionality()

Tells the number of dimensions in this tree.

Returns:

The number of dimensions.