org.faktorips.runtime.internal.tableindex
Class SearchStructure<R>

java.lang.Object
  org.faktorips.runtime.internal.tableindex.SearchStructure<R>

Type Parameters:

R - The type of the resulting values.

Direct Known Subclasses:

AbstractMapStructure, ResultStructure, UniqueResultStructure

public abstract class SearchStructure<R>
extends Object

A SearchStructure is a data structure that is used by tables to optimize index key access on their data. The fundamental idea is that a SearchStructure is a self containing composite, that means every structure contains another structure.

For each part of an index a nested SearchStructure exists. The contained SearchStructure can be retrieved via the get(Object) method, called with the key that is to be searched for. The last call is get() which then retrieves the resulting values as a Set.

To prevent NullPointerExceptions without checking for null, every get(Object) will return a valid SearchStructure. If there is no nested structure for any given key, an EmptySearchStructure is returned as a fall-back. Calling get(Object) on it (with any key) simply returns the EmptySearchStructure itself. In other words an EmptySearchStructure is a kind of null-Object.

Example: given a nested structure Map -> Tree -> Tree and the call get(x).get(y).get(z) on it. If get(x) on the map yields no result an EmptySearchStructure is returned. Nevertheless the following get(y).get(z) can be called without checking for null. The empty result is returned on every subsequent call.

See Also:

ResultStructure

Constructor Summary

SearchStructure()

Method Summary

abstract Set<R>	get() Returns the set of resulting values.
abstract SearchStructure<R>	get(Object key) Returns the nested SearchStructure for the given key.
R	getUnique() Returns the value if there is exactly one value.
R	getUnique(R defaultValue) Returns the value if there is exactly one value or the given defaultValue if this structure is empty.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SearchStructure

public SearchStructure()

Method Detail

get

public abstract SearchStructure<R> get(Object key)

Returns the nested SearchStructure for the given key. This method never returns null. If no value exists for a given key an EmptySearchStructure is returned as a fall-back.

Parameters:

key - The key for the requested nested SearchStructure

Returns:

The nested SearchStructure or an EmptySearchStructure if the key does not exist.

get

public abstract Set<R> get()

Returns the set of resulting values. If this SearchStructure is no ResultStructure this method simply aggregates every nested structures' results. Beware that the aggregation of nested elements has linear complexity.

Returns:

The set of resulting values that are reachable by this SearchStructure

getUnique

public R getUnique()

Returns the value if there is exactly one value.

Use this method if you know there should be exactly one result value. This method throws an AssertionError if there is more than one values. If there is no value it throws an NoSuchElementException exception.

Returns:

The one and only result hold by this SearchStructure.

Throws:

AssertionError - if your assertion that there is at most one element is wrong and hence there is more than one value.

NoSuchElementException - If there is no element at all.

getUnique

public R getUnique(R defaultValue)

Returns the value if there is exactly one value or the given defaultValue if this structure is empty.

Use this method if you know there should be at most one result value. This method throws an AssertionError if there is more than one value.

Parameters:

defaultValue - The defaultValue which is returned if this SearchStructure is empty.

Returns:

The result hold by this SearchStructure or the defaultValue if the structure is empty.

Throws:

AssertionError - if your assertion that there is at most one element is wrong and hence there are more than one result values.