# Class: com.pnfsoftware.jeb.util.collect.ReferenceCounter

A simple, thread\-safe object reference counter. A counter can be associated to any object of the provided `K` type. 

 Note that this utility class has nothing to do with Garbage Collection reference counting.

## Constructor: ReferenceCounter

Description: Create a new reference counter.

## Method: clear

Description: Reset the reference counter.

## Method: copyToMap
- return type: `java.util.Map<K,java.lang.Integer>`

Description: Copy the counters to a map.
return: copy of the counter map

## Method: dec
- parameter: `key`, type: `K`
- return type: `int`

Description: Unrecord an object, ie decrement its reference counter by one. If the object is currently untracked, an exception will be raised.
parameter: key: object
return: the updated counter for this object
throws: if the object is not present

## Method: formatAllReferences
- return type: `java.lang.String`

Description: Format all references in descending order.
return: a string

## Method: formatTopReferences
- parameter: `top`, type: `int`
- return type: `java.lang.String`

Description: Format the top references \(= descending order\) counted referenced by the counter.
parameter: top: the number of top references to format; a negative number means to format all            references
return: a string

## Method: get
- parameter: `key`, type: `K`
- return type: `int`

Description: Get the reference counter for an object.
parameter: key: object
return: the counter; 0 if the object is currently not tracked

## Method: getAsMap
- return type: `java.util.Map<K,java.lang.Integer>`

Description: Get a read\-only map of \(referenced object \-\> count\). To be used in a "this counter"\-synchronized block.
return: read\-only view of the internal map

## Method: getCount
- return type: `int`

Description: Get the total count for all the references actively counted by this counter.
return: sum of all counters

## Method: has
- parameter: `key`, type: `K`
- return type: `boolean`

Description: Check if an object is currently referenced, ie its reference counter is greater or equal than zero.
parameter: key: object
return: true if the object is referenced

## Method: inc
- parameter: `key`, type: `K`
- return type: `int`

Description: Record an object, ie increment its reference counter. Will raise an [IllegalStateException](IllegalStateException) if the counter exceeds the capacity of a signed integer.
parameter: key: object
return: the updated counter for this object

## Method: isEmpty
- return type: `boolean`

Description: Determine whether there are references actively tracked by this counter.
return: true if no object is tracked

## Method: keys
- return type: `java.util.Set<K>`

Description: Retrieve the tracked keys.
return: copy of the key set

## Method: load
- parameter: `coll`, type: `java.util.Collection<? extends K>`

Description: Load a collection of objects by incrementing the counter for each object.
parameter: coll: objects to count

## Method: orderedKeys
- parameter: `descending`, type: `boolean`
- return type: `java.util.Collection<K>`

Description: Retrieve keys ordered by their counters.
parameter: descending: true to sort by descending counter values
return: ordered collection of keys

## Method: remove
- parameter: `key`, type: `K`
- return type: `boolean`

Description: Remove an object from tracking. This method is equivalent to decrementing the object counter until zero.
parameter: key: object
return: true if the object was actually referenced \(ie its counter was \>= 1\), false if it was         not

## Method: size
- return type: `int`

Description: Get the number of references actively counted by this counter.
return: number of distinct tracked objects

## Method: toString
- return type: `java.lang.String`