mondrian.util

Interface SpatialValueTree2

public interface SpatialValueTree2

Variation of Luc's SpatialValueTree.

Notes:

1. For clarity, I got rid of the of template args. We might add back say '<Q extends SpatialRegionRequest, R extends SpatialRegion, D extends SpatialDimension>' if it saves a lot of casting in client code.

2. It might be useful to introduce an interface SpatialDimensionality that represents a set of dimensions. It will certainly be useful for the implementation; however, it is not clear that it is necessary in the API.

3. In mondrian a 'region value' might be a struct that contains a weak reference to a segment in cache, and a reference to a segment in an external cache. Either of the references can be null.

4. In a SpatialRegionRequest, it might be useful to coalesce a list of values into a range (e.g. {2009, 2010, 2011} would be [2009, 2011]).

Mondrian requests currently have raw values, but converting those raw values into ranges might allow the tree to be more efficient.

Ranges could be recognized if we know all allowable values. For example, if we know the set of states, we can say that {"CA", "CO", "CT" "DE"} is equivalent to ["CA", "DE"]. A range could be recognized if the data type is discreet. For example, {2009, 2010, 2011} is equivalent to [2009, 2011] because year is an int.

5. For performance, and atomicity of operations, some of the methods might contain a callback (e.g. rollup(java.util.Map) could take a functor that is applied when a rollup is found. But we can validate the design introducing functors just yet.

Author:

jhyde

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	SpatialValueTree2.SpatialDimension
static interface	SpatialValueTree2.SpatialRegion
static interface	SpatialValueTree2.SpatialRegionRequest A request for a region.

Method Summary

Modifier and Type	Method and Description
void	add(SpatialValueTree2.SpatialRegion region) Stores a region in this tree.
void	clear(SpatialValueTree2.SpatialRegion region) Removes a region from the tree.
SpatialValueTree2.SpatialRegion	get(SpatialValueTree2.SpatialRegionRequest regionRequest) Looks up all the values registered in nodes intersecting with the provided region key.
List<SpatialValueTree2.SpatialDimension>	getDimensions() Returns a list of all the dimensions present in this tree.
SpatialValueTree2.SpatialRegion	getRegionContaining(Map<SpatialValueTree2.SpatialDimension,Object> coordinates) Returns a region containing a given cell.
List<SpatialValueTree2.SpatialRegion>	rollup(Map<SpatialValueTree2.SpatialDimension,Object> dimensions) Returns a collection of regions that can be combined to compute a given cell.

Method Detail

getDimensions

List<SpatialValueTree2.SpatialDimension> getDimensions()

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

Returns:

A list of dimensions.

add

void add(SpatialValueTree2.SpatialRegion region)

Stores a region in this tree.

REVIEW: What is the behavior if there is another region with an equal SpatialValueTree2.SpatialRegionRequest?

Parameters:

region - Region

clear

void clear(SpatialValueTree2.SpatialRegion region)

Removes a region from the tree.

Parameters:

region - The region key of the values to clear.

get

SpatialValueTree2.SpatialRegion get(SpatialValueTree2.SpatialRegionRequest regionRequest)

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

REVIEW: Does it have to PRECISELY fulfill the request, or can it be a superset? Does the return value's SpatialValueTree2.SpatialRegion.getRequest() method return the regionRequest parameter? (That would be expensive to implement.) Do we even need this method, or is

Parameters:

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

Returns:

Region fulfilling the request, or null

getRegionContaining

SpatialValueTree2.SpatialRegion getRegionContaining(Map<SpatialValueTree2.SpatialDimension,Object> coordinates)

Returns a region containing a given cell.

If there are multiple regions that contain the cell, returns just one of them. If there are no regions, returns null.

Parameters:

coordinates - Coordinates of cell - a value for each constraining dimension

Returns:

a region that contains the cell, or null if there is no such

rollup

List<SpatialValueTree2.SpatialRegion> rollup(Map<SpatialValueTree2.SpatialDimension,Object> dimensions)

Returns a collection of regions that can be combined to compute a given cell.

The regions are not necessarily disjoint. Nor are they necessarily of the same dimensionality.

If multiple rollups are possible, gives the set of regions with the smallest number of cells. (It is cheaper to roll up from regions that are already highly aggregated.)

If no rollup is possible, returns null.

Parameters:

dimensions - Coordinates of cell

Returns:

List of spatial regions to roll up; or null