Package net.shibboleth.shared.collection

# Class IndexingObjectStore<T>

java.lang.Object
net.shibboleth.shared.collection.IndexingObjectStore<T>

Type Parameters:
  `T` - type of object being stored

@ThreadSafe public class IndexingObjectStore<T> extends Object

This class is used to store instances of objects that may be created independently but are, in fact, the same object. For example, KeyInfo XML structures contain keys, certs, and CRLs. Multiple unique instances of a KeyInfo may contain, and separately construct, the exact same cert. KeyInfo could, therefore, create a class-level instance of this object store and put certs within it. In this manner the cert is only sitting in memory once and each KeyInfo simply stores a reference (index) to stored object.

This store uses basic reference counting to keep track of how many of the respective objects are pointing to an entry. Adding an object that already exists, as determined by the object's `equals()` method, simply increments the reference counter. Removing an object decrements the counter. Only when the counter reaches zero is the object actually freed for garbage collection.

Note: the instance of an object returned by `get(String)` need not be the same object as stored via `put(Object)`. However, the instances will be equal according to their `equals()`. The indexing and storage is based on use of `Map`, so the normal caveats related to use of hash-based collection types apply: if the stored object's `hashCode()` and `equals()` methods are implemented based on mutable properties of the object, then those object instance's properties should not be mutated while the object is stored, otherwise unpredictable behavior will result.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`private class`
`IndexingObjectStore.StoredObjectWrapper`
Wrapper class that keeps track of the reference count for a stored object.

## Field Summary

Fields
Modifier and Type
Field
Description
`private Map<T,Integer>`
`indexStore`
Map of object instances to the index value used to reference them externally.
`private int`
`lastIndex`
The last index sequence used.
`private Map<String,IndexingObjectStore<T>.StoredObjectWrapper>`
`objectStore`
Backing object data store.
`private ReadWriteLock`
`rwLock`
Read/Write lock used to control synchronization over the backing data store.

## Constructor Summary

Constructors
Constructor
Description
`IndexingObjectStore()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`void`
`clear()`
Clears the object store.
`boolean`
`containsIndex(String index)`
Checks whether the store contains an object registered under the given index.
`boolean`
`containsInstance(T instance)`
Checks whether the store contains an object instance equal to the specified one.
`T`
`get(String index)`
Gets a registered object by its index.
`protected String`
`getIndex(T object)`
Get the index for the specified object.
`boolean`
`isEmpty()`
Checks if the store is empty.
`String`
`put(T object)`
Adds the given object to the store.
`void`
`remove(String index)`
Removes the object associated with the given index.
`protected void`
`removeIndex(T object)`
Remove the index for the specified object.
`int`
`size()`
Gets the total number of unique items in the store.

### Methods inherited from class java.lang.Object

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

## Field Details

### rwLock

@Nonnull private ReadWriteLock rwLock
Read/Write lock used to control synchronization over the backing data store.

### objectStore

@Nonnull private Map<String,IndexingObjectStore<T>.StoredObjectWrapper> objectStore
Backing object data store.

### indexStore

@Nonnull private Map<T,Integer> indexStore
Map of object instances to the index value used to reference them externally.

### lastIndex

private int lastIndex
The last index sequence used.

## Constructor Details

### IndexingObjectStore

public IndexingObjectStore()
Constructor.

## Method Details

### clear

public void clear()
Clears the object store.

### containsIndex

public boolean containsIndex(String index)
Checks whether the store contains an object registered under the given index.

Parameters:
  `index` - the index to check
Returns:
  true if an object is associated with the given index, false if not

### containsInstance

public boolean containsInstance(T instance)
Checks whether the store contains an object instance equal to the specified one.

Parameters:
  `instance` - the object instance to check
Returns:
  true if an object instance equal to the specified one is stored, false if not

### isEmpty

public boolean isEmpty()
Checks if the store is empty.

Returns:
  true if the store is empty, false if not

### put

public String put(T object)
Adds the given object to the store. Technically this method only adds the object if it does not already exist in the store. If it does this method simply increments the reference count of the object.

Parameters:
  `object` - the object to add to the store, may be null
Returns:
  the index that may be used to later retrieve the object or null if the object was null

### get

public T get(String index)
Gets a registered object by its index.

Parameters:
  `index` - the index of an object previously registered, may be null
Returns:
  the registered object or null if no object is registered for that index

### remove

public void remove(String index)
Removes the object associated with the given index. Technically this method decrements the reference counter to the object. If, after the decrement, the reference counter is zero then, and only then, is the object actually freed for garbage collection.

Parameters:
  `index` - the index of the object, may be null

### size

public int size()
Gets the total number of unique items in the store. This number is unaffected by the reference count of the individual stored objects.

Returns:
  number of items in the store

### getIndex

protected String getIndex(T object)
Get the index for the specified object.

Parameters:
  `object` - the target object
Returns:
  the object index value

### removeIndex

protected void removeIndex(T object)
Remove the index for the specified object.

Parameters:
  `object` - the target index