com.cloudhopper.commons.util

Class DigitLookupMap<V>

java.lang.Object

com.cloudhopper.commons.util.DigitLookupMap<V>

All Implemented Interfaces:

SimpleMap<V>

public class DigitLookupMap<V>
extends Object
implements SimpleMap<V>

A Trie based implementation of the SimpleMap interface used to map String keys (containing only digits) to values. This implementation supports prefix and/or specific key matches. The caller can explicitly permit a key to match a prefix or specific value by appending a '*' character on the end. This class guarantees that the map will be in numerically ascending key order, sorted according to the natural order for the key's prefix and specific key values.
A "specific" key contains only digits such as "13135551212". Specific keys will only match lookups that precisely match the key used. A "prefix" key contains zero or more digits, followed by a "*" character. Prefix keys will match the best value.
Looking up a key of length (m) takes a worst case O(m) time. This Trie based implementation is a super efficient way of storing a large number of digit-only Strings, especially when many of the Strings contain the same prefix. The keys are not stored explicitly and nodes are shared between keys with common initial subsequences.

Author:

joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Constructor Summary

Constructors

Constructor and Description
DigitLookupMap()

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	assertValidGetKey(String key)
protected static void	assertValidKey(String key)
protected static void	assertValidPutKey(String key)
void	debug(PrintStream out) Prints out a dump of the hierarchy of this AddressTree to the specified PrintStream.
V	get(String key) Returns the value to which this map maps the specified key.
V	put(String key, V value) Associates the value with the key in this map.
int	size() Returns the number of key-value mappings in this map.
protected static int	toNodeArrayIndex(char c) Returns the node array index of the character for 0-9, or 10 for the '*' character.

Methods inherited from class java.lang.Object

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

Constructor Detail

DigitLookupMap

public DigitLookupMap()

Method Detail

size

public int size()

Returns the number of key-value mappings in this map. This underlying implementation includes both specific and prefix mappings are part of the size. A null value does not count as a key-value mapping.

Specified by:

size in interface SimpleMap<V>

Returns:

The number of key-value mappings in this map.

get

public V get(String key)
      throws IllegalArgumentException

Description copied from interface: SimpleMap

Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

Specified by:

get in interface SimpleMap<V>

Parameters:

key - The key whose associated value is to be returned.

Returns:

The value to which this map maps the specified key, or null if the map contains no mapping for this key.

Throws:

IllegalArgumentException - Thrown if the key or value is not valid

put

public V put(String key,
    V value)
      throws IllegalArgumentException

Associates the value with the key in this map. If the map previously contained a mapping for this key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.)

Specified by:

put in interface SimpleMap<V>

Parameters:

key - The key with which the specified value is to be associated. Null keys are not permitted and will throw a NullPointerException.

value - The value to be associated with the specified key.

Returns:

The previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

Throws:

IllegalArgumentException - Thrown if the key or value is not valid

assertValidKey

protected static void assertValidKey(String key)
                              throws NullPointerException,
                                     IllegalArgumentException

Throws:

NullPointerException

IllegalArgumentException

assertValidGetKey

protected static void assertValidGetKey(String key)
                                 throws NullPointerException,
                                        IllegalArgumentException

Throws:

NullPointerException

IllegalArgumentException

assertValidPutKey

protected static void assertValidPutKey(String key)
                                 throws NullPointerException,
                                        IllegalArgumentException

Throws:

NullPointerException

IllegalArgumentException

toNodeArrayIndex

protected static int toNodeArrayIndex(char c)

Returns the node array index of the character for 0-9, or 10 for the '*' character. Returns -1 if no mapping exists.

debug

public void debug(PrintStream out)

Prints out a dump of the hierarchy of this AddressTree to the specified PrintStream.