Package com.apama.correlator.memstore

Class AbstractTable

java.lang.Object

com.apama.correlator.memstore.AbstractTable

All Implemented Interfaces:

java.lang.Iterable<java.util.Map.Entry<java.lang.String,RowValue>>

Direct Known Subclasses:

ConcurrentMapAdapter

public abstract class AbstractTable
extends java.lang.Object
implements java.lang.Iterable<java.util.Map.Entry<java.lang.String,RowValue>>

A table exposed by a distributed store, providing the ability to get and modify the Rows that hold the key/value data held by the cache.

If the distributed store implementation provides a ConcurrentMap, then it is recommended that implementers of Apama distributed store drivers create subclasses of ConcurrentMapAdapter instead of subclassing AbstractTable directly, for ease of development and maintenance.

Implementations of this class must be thread-safe.

Drivers may optionally provide support for 'row changed' notifications. To do this, subclasses must create an implementation of RowChangedSubscriptionManager and return it from getRowChangedSubscriptionManager(), as well as calling fireRowChanged when changes are detected. Calls to subscribeRowChanged and unsubscribe are passed to this instance.

A table may optionally implement TableSupportsExtraFields if it supports the use of extraFields.

See Also:

TableSupportsExtraFields, ConcurrentMapAdapter

Constructor Summary

Constructors

Constructor	Description
AbstractTable()	Creates a table.

Method Summary

Modifier and Type	Method	Description
abstract void	clear()	Removes all of the mappings from this map (optional operation).
void	close()	Closes resources allocated by this table such as the RowChangedSubscriptionManager.
abstract boolean	containsKey(java.lang.String key)	Returns true if this map contains a mapping for the specified key.
abstract RowValue	get(java.lang.String key)	Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
RowChangedSubscriptionManager	getRowChangedSubscriptionManager()	Retrieves the RowChangedSubscriptionManager instance for this table if row changed notifications are supported.
abstract java.util.Iterator<java.util.Map.Entry<java.lang.String,RowValue>>	iterator()	Returns an iterator over all the rows of this table.
void	put(java.lang.String key, RowValue value)	Associates the specified key with the given value.
abstract RowValue	putIfAbsent(java.lang.String key, RowValue value)	If the specified key is not already associated with a value, associates it with the given value.
abstract RowValue	remove(java.lang.String key)	Removes the mapping for a key from this map if it is present.
abstract boolean	remove(java.lang.String key, RowValue value)	Removes the entry for a key only if currently mapped to a given value.
abstract boolean	replace(java.lang.String key, RowValue oldValue, RowValue newValue)	Replaces the entry for a key only if it is currently mapped to a given value.
abstract int	size()	Returns the number of key-value mappings in this map.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

AbstractTable

public AbstractTable()

Creates a table.

Method Detail

get

public abstract RowValue get(java.lang.String key)

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

Parameters:

key - the key whose associated value is to be returned

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys

clear

public abstract void clear()

Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.

Throws:

java.lang.UnsupportedOperationException - if the clear operation is not supported by this map

remove

public abstract RowValue remove(java.lang.String key)

Removes the mapping for a key from this map if it is present. More formally, if this map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one such mapping.)

Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key.

Parameters:

key - key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or null if there was no mapping for key

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this map

remove

public abstract boolean remove(java.lang.String key,
                               RowValue value)

Removes the entry for a key only if currently mapped to a given value.

Parameters:

key - key with which the specified value is associated

value - value expected to be associated with the specified key

Returns:

true if the value was removed

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this map

replace

public abstract boolean replace(java.lang.String key,
                                RowValue oldValue,
                                RowValue newValue)

Replaces the entry for a key only if it is currently mapped to a given value. Compare and swap.

Parameters:

key - key with which the specified value is associated

oldValue - value expected to be associated with the specified key

newValue - value to be associated with the specified key

Returns:

true if the value was replaced

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map

java.lang.ClassCastException - if the class of a specified key or value prevents it from being stored in this map

java.lang.NullPointerException - if a specified key or value is null, and this map does not permit null keys or values

java.lang.IllegalArgumentException - if some property of a specified key or value prevents it from being stored in this map

putIfAbsent

public abstract RowValue putIfAbsent(java.lang.String key,
                                     RowValue value)

If the specified key is not already associated with a value, associates it with the given value.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

null if there was no mapping for the key. The current value associated with the specified key if a mapping already existed.

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map

java.lang.NullPointerException - if the specified key or value is null, and this map does not permit null keys or values

java.lang.IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map

put

public void put(java.lang.String key,
                RowValue value)

Associates the specified key with the given value. If an entry for the given key already exists then the entry is replaced.

The default implementation of this method throws UnsupportedOperationException. Subclasses should override this method and have it perform unconditional put if required.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key throws UnsupportedOperationException if the unconditional put is not supported by this map.

containsKey

public abstract boolean containsKey(java.lang.String key)

Returns true if this map contains a mapping for the specified key.

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key

size

public abstract int size()

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of key-value mappings in this map

iterator

public abstract java.util.Iterator<java.util.Map.Entry<java.lang.String,RowValue>> iterator()

Returns an iterator over all the rows of this table.

Note: a simple way to construct a Map.Entry is to use the AbstractMap.SimpleEntry class.

Specified by:

iterator in interface java.lang.Iterable<java.util.Map.Entry<java.lang.String,RowValue>>

Returns:

an iterator

getRowChangedSubscriptionManager

public RowChangedSubscriptionManager getRowChangedSubscriptionManager()

Retrieves the RowChangedSubscriptionManager instance for this table if row changed notifications are supported.

The default implementation of this method will return null, indicating that row changed notifications are not supported. Subclasses that implement notifications should override this method and have it return the instance of RowChangedSubscriptionManager for this table that provides implementations of addRowChangedListener and removeRowChangedListener and calls fireRowChanged when changes are detected. Calls to subscribeRowChanged and unsubscribe are passed to this instance. If null, the subscribe and unsubscribe EPL methods will fail with an error.

This method may be called from any thread, so to ensure thread-safety the field holding the subscription manager returned by this method should usually be marked 'final'.

Returns:

the subscriptionManager or null if notifications are not supported.

close

public void close()

Closes resources allocated by this table such as the RowChangedSubscriptionManager. If the driver called AbstractStore.registerCloseHandlerForTable(AbstractTable) when creating the table then this method will automatically called by the owning store during AbstractStore.close to clear up any table-specific resources such as the notifications manager; otherwise, the driver must do this manually.