IndexCache (eBus Utilities 5.1.0 API)

java.lang.Object
- net.sf.eBus.util.IndexCache

```
public final class IndexCache
extends Object
```
Persists a one or more 4-byte, integer index values to a specified file. This class allows an application to track an index value across executions. An example of this is tracking the incoming and outgoing sequence numbers used by a communication protocol.
An index cache is created by calling open and passing in the cache file name. If the index cache is currently open, then the existing instance is returned. Otherwise, if the file either does not exist or is of zero length, then a new index cache is created, containing no indices. If the file exists and is of non-zero length, the cache file is opened and its subordinate indices are read in. The indexCount() method returns the number of subordinate indices in the cache.

An IndexCache.Index instance is retrieved by calling getIndex. A new index is added to the cache by calling addIndex. An index may have either a positive increment or a negative increment. If positive, then the initial index must be ≤ to the final index. If negative, then the initial index must by ≥ to the final index. The increment may not be zero. An existing index is removed from the cache via the method removeIndex.

The method IndexCache.Index.nextIndex() returns the incremented index. If the increment index exceeds the final index (either > or < depending on whether the increment is > or < zero), then the "reset on final index" flag is checked to determine what to do next. If this flag is true, then the index is reset to the initial index value and that value is returned. If false, then an IndexOutOfBoundsException is thrown and the index can no longer be used.

A long is used because that will support all other integer types. For smaller integer types, configure the instance accordingly.

Note: the cache file is not written only when the index cache is closed. This class puts adds a thread to the Runtime.addShutdownHook(java.lang.Thread). This thread closes all open index cache files when the JVM shuts down.

This class does not support sharing the index cache file between simultaneously executing applications. Such use will corrupt the index file and result in undetermined results. Neither IndexCache nor IndexCache.Index classes are thread-safe. If there is a need to share an IndexCache instance among threads, then the application performs the appropriate synchronization. The static data member open(String) and isCacheOpen(java.lang.String) are thread-safe.

If you want unique, reusable index values that do not need to be persisted between application executions, then use IndexPool.

Author:

Charles Rapp

See Also:

IndexPool

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class IndexCache.Index
Tracks the individual index parameters and its location within the cache file.

Nested Classes
Modifier and Type	Class and Description
`static class`	`IndexCache.Index` Tracks the individual index parameters and its location within the cache file.

Field Summary

Fields
Modifier and Type	Field and Description
`static boolean`	`DEFAULT_AUTO_RESET` Automatic index reset is turned off by default.
`static long`	`DEFAULT_FINAL_INDEX` The default final index is `Long.MAX_VALUE`.
`static long`	`DEFAULT_INCREMENT` The default index increment is one.
`static long`	`DEFAULT_INITIAL_INDEX` The default initial index is zero.
`static int`	`MAXIMUM_INDEX_NAME_LENGTH` An index name may be at most 20 characters long.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`IndexCache.Index`	`addIndex(String indexName, long initialIndex, long finalIndex, long increment, boolean resetFlag)` Returns the new index added to the cache.
`String`	`cacheFileName()` Returns the cache file name as originally supplied by user.
`void`	`clearIndices()` Removes all indices from the cache leaving the cache empty.
`void`	`close()` Closes the cache file and removes this index cache from the map.
`boolean`	`containsIndex(String indexName)` Returns `true` if this cache contains the named index and `false` otherwise.
`IndexCache.Index`	`getIndex(String indexName)` Returns the named index instance.
`int`	`indexCount()` Returns the number of indices in this cache.
`List<String>`	`indexNames()` Returns a list of current index names.
`static boolean`	`isCacheOpen(String cacheName)` Returns `true` if the named index cache is open and `false` if it is not.
`boolean`	`isEmpty()` Returns `true` if this cache has no indices and `false` if it has at least one index.
`Date`	`lastModified()` Returns the timestamp when the cache was last modified.
`static IndexCache`	`open(String cacheFileName)` Returns the `IndexCache` instance associated with `cacheFileName`.
`boolean`	`removeIndex(String indexName)` Returns `true` if the named index was removed and `false` if the index is unknown.
`void`	`resetAllIndices()` Resets all indices to their respective initial values.
`String`	`toString()` Returns a textual representation of this index cache.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_INITIAL_INDEX
```
public static final long DEFAULT_INITIAL_INDEX
```
    The default initial index is zero.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_FINAL_INDEX
```
public static final long DEFAULT_FINAL_INDEX
```
    The default final index is Long.MAX_VALUE.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_INCREMENT
```
public static final long DEFAULT_INCREMENT
```
    The default index increment is one.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_AUTO_RESET
```
public static final boolean DEFAULT_AUTO_RESET
```
    Automatic index reset is turned off by default.
    
    See Also:
    
    Constant Field Values
  - MAXIMUM_INDEX_NAME_LENGTH
```
public static final int MAXIMUM_INDEX_NAME_LENGTH
```
    An index name may be at most 20 characters long.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - cacheFileName
```
public String cacheFileName()
```
    Returns the cache file name as originally supplied by user.
    
    Returns:
    
    the cache file name.
  - lastModified
```
public Date lastModified()
```
    Returns the timestamp when the cache was last modified. This value is set to the cache file last modified date when opened or to the current date and time when created.
    
    Returns:
    
    the timestamp when the cache was last modified.
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if this cache has no indices and false if it has at least one index.
    
    Returns:
    
    true if this cache has no indices and false if it has at least one index.
  - indexCount
```
public int indexCount()
```
    Returns the number of indices in this cache.
    
    Returns:
    
    the number of indices in this cache.
  - indexNames
```
public List<String> indexNames()
```
    Returns a list of current index names. The returned list is a copy of the actual list and so may be modified without impacting the actual list.
    
    Returns:
    
    a list of current index names.
  - containsIndex
```
public boolean containsIndex(String indexName)
```
    Returns true if this cache contains the named index and false otherwise.
    
    Parameters:
    
    indexName - the index name.
    
    Returns:
    
    true if this cache contains the named index and false otherwise.
    
    See Also:
    
    getIndex(String), addIndex(String, long, long, long, boolean), removeIndex(String)
  - getIndex
```
public IndexCache.Index getIndex(String indexName)
```
    Returns the named index instance. May return null.
    
    Parameters:
    
    indexName - the index name.
    
    Returns:
    
    the specified named index instance.
    
    See Also:
    
    containsIndex(String), addIndex(String, long, long, long, boolean), removeIndex(String)
  - isCacheOpen
```
public static boolean isCacheOpen(String cacheName)
```
    Returns true if the named index cache is open and false if it is not.
    
    Parameters:
    
    cacheName - the index cache file name.
    
    Returns:
    
    true if the named index cache is open and false if it is not.
  - addIndex
```
public IndexCache.Index addIndex(String indexName,
                                 long initialIndex,
                                 long finalIndex,
                                 long increment,
                                 boolean resetFlag)
                          throws IllegalArgumentException
```
    Returns the new index added to the cache. Note that increment may be either > or < zero and that initialIndex may equal finalIndex.
    Parameters:
    
    indexName - the index name. Must be unique within this IndexCache.
    
    initialIndex - the index initial value.
    
    finalIndex - the index maximum value. The index will not exceed this value.
    
    increment - increment the current value by this amount to get the next index value. The increment may be either > zero or < zero.
    
    resetFlag - if true, then reset the index to the initial value when the final value is exceeded.
    
    Returns:
    
    the newly added index.
    
    Throws:
    IllegalArgumentException - if:
    
    if indexName is null, an empty string or longer than MAXIMUM_INDEX_NAME_LENGTH,
    
    if indexName is not unique within this IndexCache instance,
    
    increment is zero,
    
    initialIndex is > finalIndex and increment is > zero or
    
    initialIndex is < finalIndex and increment is < zero
  - removeIndex
```
public boolean removeIndex(String indexName)
```
    Returns true if the named index was removed and false if the index is unknown.
    
    Parameters:
    
    indexName - remove the named index at this position.
    
    Returns:
    
    true if the named index was removed and false if the index is unknown.
  - resetAllIndices
```
public void resetAllIndices()
```
    Resets all indices to their respective initial values.
  - clearIndices
```
public void clearIndices()
```
    Removes all indices from the cache leaving the cache empty.
  - close
```
public void close()
```
    Closes the cache file and removes this index cache from the map. This index cache must be re-opened before it may be used again.
    
    See Also:
    
    open(java.lang.String)
  - toString
```
public String toString()
```
    Returns a textual representation of this index cache.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a textual representation of this index cache.
  - open
```
public static IndexCache open(String cacheFileName)
                       throws IllegalArgumentException,
                              IOException
```
    Returns the IndexCache instance associated with cacheFileName. If the instance is already open, that instance is returned. Otherwise the cache file's existence is tested. If the file does not exist or is of size zero, then returns a new, empty IndexCache instance. Otherwise, the cache file is opened for reading and writing, the index information is read in and the instance is created from the data.
    
    Parameters:
    
    cacheFileName - read in the index data from this file.
    
    Returns:
    
    the index cache instance associated with the file name.
    
    Throws:
    
    IllegalArgumentException - if cacheFileName is either null or empty.
    
    IOException - if cacheFileName exists but contains corrupted data.

Class IndexCache

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_INITIAL_INDEX

DEFAULT_FINAL_INDEX

DEFAULT_INCREMENT

DEFAULT_AUTO_RESET

MAXIMUM_INDEX_NAME_LENGTH

Method Detail

cacheFileName

lastModified

isEmpty

indexCount

indexNames

containsIndex

getIndex

isCacheOpen

addIndex

removeIndex

resetAllIndices

clearIndices

close

toString

open