net.sf.kdgcommons.util

Class Counters<K>

java.lang.Object

net.sf.kdgcommons.util.Counters<K>

All Implemented Interfaces:

Iterable<Map.Entry<K,Long>>, Map<K,Long>

public class Counters<K>
extends Object
implements Map<K,Long>, Iterable<Map.Entry<K,Long>>

A Map of thread-safe counters, identified by a user-defined key. Typically used to aggregate information from a stream of data.

Counters are created explicitly by putting a value, implicitly by incrementing a value that has not yet been set. Counters may be set, retrieved, incremented, decremented, or removed. You can deal with counters as primitive long values, or as Long objects.

Mmappings are stored in a ConcurrentHashMap; behavior of iterators and set retrieval methods reflect this fact. Note, however, that this class does not implement ConcurrentMap, because the internal storage is not conducive to implementing replace() and similar methods (at least not without adding lots of locks that aren't needed for the common case).

Values may not be null.

Since:

1.0.10

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
Counters()

Method Summary

Modifier and Type	Method and Description
void	clear()
boolean	containsKey(Object key) Returns true if the underlying map contains the specified key.
boolean	containsValue(Object value) Returns true if the underlying map contains the specified value.
long	decrement(K key) Decrements the specified counter, creating it if necessary.
Set<Map.Entry<K,Long>>	entrySet() Returns the current mappings.
Long	get(Object key) Returns the value associated with the specified key, null if there is not a mapping for the key.
int	getInt(K key) Retrieves the value of the specified key as a primitive int.
long	getLong(K key) Retrieves the value of the specified key as a primitive long.
long	increment(K key) Increments the specified counter, creating it if necessary.
boolean	isEmpty() Returns true if the underlying map is empty.
Iterator<Map.Entry<K,Long>>	iterator() Returns an iterator for the entries in the map.
Set<K>	keySet() Returns the current keys in the map.
Long	put(K key, Long newValue) Stores a new mapping, returning the previous mapping.
void	putAll(Map<? extends K,? extends Long> map) Initializes this object from the passed map.
Long	putIfAbsent(K key, Long value) Adds a mapping for the value, if one does not already exist.
void	putLong(K key, long value) Sets the mapping to the specified value.
Long	remove(Object key) Removes a mapping and returns it.
int	size() Returns the number of mappings (distinct keys) in this object.
String	toString() Outputs all counters in the format "[ NAME: VALUE, ...]".
Collection<Long>	values() Returns the current values in the map.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, remove, replace, replace, replaceAll

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

Counters

public Counters()

Method Detail

toString

public String toString()

Outputs all counters in the format "[ NAME: VALUE, ...]".

Overrides:

toString in class Object

size

public int size()

Returns the number of mappings (distinct keys) in this object.

Specified by:

size in interface Map<K,Long>

isEmpty

public boolean isEmpty()

Returns true if the underlying map is empty.

Specified by:

isEmpty in interface Map<K,Long>

containsKey

public boolean containsKey(Object key)

Returns true if the underlying map contains the specified key.

Specified by:

containsKey in interface Map<K,Long>

containsValue

public boolean containsValue(Object value)

Returns true if the underlying map contains the specified value. The passed value must be a Number; its longValue is tested against the values in the map.

As this operation iterates the map, it represents a point in time, and may not reflect concurrent updates (of course, why anyone would test for a value at the same time they're updating the map is a mystery to me).

Specified by:

containsValue in interface Map<K,Long>

get

public Long get(Object key)

Returns the value associated with the specified key, null if there is not a mapping for the key. Note that this behavior differs from getLong(K), which returns 0 if there is no mapping for the key.

Specified by:

get in interface Map<K,Long>

put

public Long put(K key,
                Long newValue)

Stores a new mapping, returning the previous mapping.

This method does not attempt to prevent multiple threads from updating the map at the same time; concurrent calls could return the same old value. If this is a problem for you, call putIfAbsent(K, java.lang.Long).

Specified by:

put in interface Map<K,Long>

remove

public Long remove(Object key)

Removes a mapping and returns it. If called concurrently, only one call will actually remove the value.

Specified by:

remove in interface Map<K,Long>

putAll

public void putAll(Map<? extends K,? extends Long> map)

Initializes this object from the passed map. This is not an atomic operation; each value is added individually, and other threads are allowed to update the map concurrently.

Specified by:

putAll in interface Map<K,Long>

clear

public void clear()

Specified by:

clear in interface Map<K,Long>

keySet

public Set<K> keySet()

Returns the current keys in the map. Note that this represents a point-in-time view of the map, so if you are concurrently adding or removing counters it may be missing keys or contain keys that are no longer in the map.

Specified by:

keySet in interface Map<K,Long>

values

public Collection<Long> values()

Returns the current values in the map. This operation involves a translation from internal representation to Long, so is relatively inefficient. As it uses the underlying map iterator to work, the returned collection may not reflect concurrent updates.

Specified by:

values in interface Map<K,Long>

entrySet

public Set<Map.Entry<K,Long>> entrySet()

Returns the current mappings. This involves a translation from internal representation, so is relatively inefficient; if you want to iterate the map, call iterator().

Specified by:

entrySet in interface Map<K,Long>

putIfAbsent

public Long putIfAbsent(K key,
                        Long value)

Adds a mapping for the value, if one does not already exist. See the JavaDoc for ConcurrentMap.putIfAbsent() for behavior.

Specified by:

putIfAbsent in interface Map<K,Long>

getLong

public long getLong(K key)

Retrieves the value of the specified key as a primitive long. If there is no mapping for the key, returns 0.

getInt

public int getInt(K key)

Retrieves the value of the specified key as a primitive int. If there is no mapping for the key, returns 0. This is only valid if you know that your counters will remain in integer range (but often works better with other variables in your code).

putLong

public void putLong(K key,
                    long value)

Sets the mapping to the specified value. This is equivalent to calling put(K, java.lang.Long), with the same caveats regarding concurent access.

increment

public long increment(K key)

Increments the specified counter, creating it if necessary. This method may be called concurrently without fear of a race condition (even when creating a new counter).

Returns:

The current (post-increment) value of the counter.

decrement

public long decrement(K key)

Decrements the specified counter, creating it if necessary. This method may be called concurrently without fear of a race condition (even when creating a new counter).

Returns:

The current (post-increment) value of the counter.

iterator

public Iterator<Map.Entry<K,Long>> iterator()

Returns an iterator for the entries in the map. The returned iterator represents a point in time; it is not subject to concurrent modification exceptions, but does not reflect any changes after it is retrieved.

Specified by:

iterator in interface Iterable<Map.Entry<K,Long>>