org.terracotta.toolkit
Interface Toolkit


public interface Toolkit

A toolkit that provides various data-structures. A Toolkit can be constructed using one of the factory methods provided in ToolkitFactory. See ToolkitFactory for more details on how to instantiate a toolkit.

All object instances constructed using the toolkit are always identified by a name. Some instances can be destroyed, and in such cases the objects will also be instance of Destroyable. Some instances also perform lock-based mutate and read operations based on a read-write lock associated with the instance, these are instances of ToolkitLockedObject. There are certain optional features in the toolkit denoted by ToolkitFeatureType. Certain implementations can support these features. Users can use ToolkitFeature.isEnabled() at runtime to check whether the specific feature is enabled or not. Some toolkit implementations can be distributed in nature, for example Terracotta clustered toolkits, and in such cases can support the getClusterInfo() api. Toolkit implementations that are not distributed in nature can throw UnsupportedOperationException for the same. Toolkit implementors can also choose to implement operator events, for easy monitoring, and support the fireOperatorEvent(OperatorEventLevel, String, String) or otherwise throw UnsupportedOperationException.

Destroy Behavior

Toolkit objects that can be destroyed are instances of Destroyable and once destroyed cannot be reused. Attempting to use an object after getting destroyed will result in IllegalStateException except for ToolkitObject.getName(). In toolkit implementations which are distributed in nature, like Terracotta clustered toolkits, destroying an object in one node will destroy it from all the nodes in the cluster, attempting to use the destroyed instance in any other node will also result in IllegalStateException. It is though possible to reuse the same name of an already destroyed instance by calling the corresponding Toolkit.getXXX(String name) method with the same name. The new object references thus obtained will work, while the old references that pointed to the 'destroyed' object instance will throw IllegalStateException.

For those who want to implement the toolkit should consult ToolkitFactoryService.


Method Summary
 void fireOperatorEvent(OperatorEventLevel level, String applicationName, String eventMessage)
          Fires an application specific Operator Event with the specified OperatorEventLevel and eventMessage.
 ToolkitAtomicLong getAtomicLong(String name)
          Returns a ToolkitAtomicLong for the given name parameter.
 ToolkitBarrier getBarrier(String name, int parties)
          Returns a ToolkitBarrier for the given name and specified parties.
<E> ToolkitBlockingQueue<E>
getBlockingQueue(String name, Class<E> klazz)
          Get or create a toolkit blocking queue for the given name.
<E> ToolkitBlockingQueue<E>
getBlockingQueue(String name, int capacity, Class<E> klazz)
          Get or create a toolkit blocking queue with a capacity limit for the given name.
<V> ToolkitCache<String,V>
getCache(String name, Class<V> klazz)
          Returns an already created ToolkitCache if one exists for the given name, otherwise creates one and returns it.
<V> ToolkitCache<String,V>
getCache(String name, Configuration configuration, Class<V> klazz)
          Returns an already created ToolkitCache if one exists for the given name parameter, otherwise creates one using the configuration parameter and returns it.
 ClusterInfo getClusterInfo()
          Gets the ClusterInfo associated with the toolkit.
<T extends ToolkitFeature>
T
getFeature(ToolkitFeatureType<T> type)
          Returns the ToolkitFeature implementation identified by type associated with the Toolkit.
<E> ToolkitList<E>
getList(String name, Class<E> klazz)
          Returns an already created ToolkitList if one exists for the given name parameter, otherwise creates one and returns it.
 ToolkitLock getLock(String name)
          Get a reentrant toolkit write lock of the specified name.
<K,V> ToolkitMap<K,V>
getMap(String name, Class<K> keyKlazz, Class<V> valueKlazz)
          Returns an already created ToolkitMap if one exists for the given name, otherwise creates one and returns it.
<E> ToolkitNotifier<E>
getNotifier(String name, Class<E> klazz)
          Gets or creates a ToolkitNotifier for the given name parameter.
 ToolkitReadWriteLock getReadWriteLock(String name)
          Get a reentrant toolkit read-write lock for the given name.
<E> ToolkitSet<E>
getSet(String name, Class<E> klazz)
          Returns an already created ToolkitSet if one exists for the given name parameter, otherwise creates one and returns it.
<K extends Comparable<? super K>,V>
ToolkitSortedMap<K,V>
getSortedMap(String name, Class<K> keyKlazz, Class<V> valueKlazz)
          Returns an already created ToolkitSortedMap if one exists for the given name, otherwise creates one and returns it.
<E extends Comparable<? super E>>
ToolkitSortedSet<E>
getSortedSet(String name, Class<E> klazz)
          Returns an already created ToolkitSortedSet if one exists for the given name parameter, otherwise creates one and returns it.
<V> ToolkitStore<String,V>
getStore(String name, Class<V> klazz)
          Returns an already created ToolkitStore if one exists for the given name, otherwise creates one and returns it.
<V> ToolkitStore<String,V>
getStore(String name, Configuration configuration, Class<V> klazz)
          Returns an already created ToolkitStore if one exists for the given 'name' parameter, otherwise creates one using the 'configuration' parameter and returns it.
 void shutdown()
          Shut down toolkit and release resources associated with the toolkit.
 

Method Detail

getList

<E> ToolkitList<E> getList(String name,
                           Class<E> klazz)
Returns an already created ToolkitList if one exists for the given name parameter, otherwise creates one and returns it.

Toolkit lists are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
E - list element type
Parameters:
name - identifier of the list
klazz - concrete class for <E>
Returns:
a toolkit list

getStore

<V> ToolkitStore<String,V> getStore(String name,
                                    Configuration configuration,
                                    Class<V> klazz)
Returns an already created ToolkitStore if one exists for the given 'name' parameter, otherwise creates one using the 'configuration' parameter and returns it. Subsequent calls to getStore() with same name will return same key-value store. The configuration parameter can take various config. Keys in the mapping can take values declared in ToolkitConfigFields. Behavior of the various configs are detailed in below table:
Configuration Field Default Value Instance exists in Cluster already Instance does NOT exist in Cluster yet
value passed in config value NOT passed in config value passed in config value NOT passed in config
CONSISTENCY EVENTUAL IllegalArgumentException on mismatch Use existing value Use value passed in config Use default value
CONCURRENCY 256 IllegalArgumentException on mismatch Use existing value Use value passed in config Use default value
MAX_COUNT_LOCAL_HEAP 0 Use local value for first time in same node, throws IllegalArgumentException on mismatch thereafter Use existing value Use value passed in config Use default value
MAX_BYTES_LOCAL_HEAP 0 Use local value for first time in same node, throws IllegalArgumentException on mismatch thereafter Use existing value Use value passed in config Use default value
MAX_BYTES_LOCAL_OFF_HEAP 0 Use local value for first time in same node, throws IllegalArgumentException on mismatch thereafter Use existing value Use value passed in config Use default value
OFF_HEAP_ENABLED false Use local value for first time in same node, throws IllegalArgumentException on mismatch thereafter Use existing value Use value passed in config Use default value
LOCAL_CACHE_ENABLED true Use local value for first time in same node, throws IllegalArgumentException on mismatch thereafter Use existing value Use value passed in config Use default value

Toolkit key-value stores are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
V - store value type
Parameters:
name - identifier for the key-value store
configuration - configuration with which the key-value store is to be created
klazz - concrete class for <V>
Returns:
a toolkit key-value store

getStore

<V> ToolkitStore<String,V> getStore(String name,
                                    Class<V> klazz)
Returns an already created ToolkitStore if one exists for the given name, otherwise creates one and returns it. It uses a default Toolkit Store config and is effectively same as below:
 public ToolkitStore getStore(String name) {
   return getStore(name, new ToolkitStoreConfigBuilder().build());
 }
 

Toolkit key-value stores are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
V - store value type
Parameters:
name - identifier for the key-value store
klazz - concrete class for <V>
Returns:
a toolkit key-value store with default configuration

getMap

<K,V> ToolkitMap<K,V> getMap(String name,
                             Class<K> keyKlazz,
                             Class<V> valueKlazz)
Returns an already created ToolkitMap if one exists for the given name, otherwise creates one and returns it.

Toolkit maps are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
K - map key type
V - map value type
Parameters:
name - identifier for the map
keyKlazz - concrete class for <K>
valueKlazz - concrete class for <V>
Returns:
a toolkit map

getSortedMap

<K extends Comparable<? super K>,V> ToolkitSortedMap<K,V> getSortedMap(String name,
                                                                       Class<K> keyKlazz,
                                                                       Class<V> valueKlazz)
Returns an already created ToolkitSortedMap if one exists for the given name, otherwise creates one and returns it.

Toolkit Sorted maps are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
K - map key type
V - map value type
Parameters:
name - identifier for the map
keyKlazz - concrete class for <K>
valueKlazz - concrete class for <V>
Returns:
a toolkit map

getBlockingQueue

<E> ToolkitBlockingQueue<E> getBlockingQueue(String name,
                                             int capacity,
                                             Class<E> klazz)
Get or create a toolkit blocking queue with a capacity limit for the given name.

If the named queue already exists and it has the same capacity limit then it is returned. If it doesn't exist then it is created and registered. If the named queue already exists but has a different capacity limit then IllegalArgumentException is thrown.
NOTE: Integer.MAX_VALUE is a valid capacity and it does NOT mean unbounded queue.

Toolkit queues are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
E - queue element type
Parameters:
name - identifier for the queue
capacity - the capacity limit for the queue
klazz - concrete class for <E>
Returns:
a capacity bounded toolkit blocking queue
Throws:
IllegalArgumentException - if there is an existing queue of same name with a different capacity limit
IllegalArgumentException - if capacity is less than 1.

getBlockingQueue

<E> ToolkitBlockingQueue<E> getBlockingQueue(String name,
                                             Class<E> klazz)
Get or create a toolkit blocking queue for the given name. This is same as calling Toolkit.getBlockingQueue(name, Integer.MAX_VALUE)

See getBlockingQueue(String, int, Class).

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
E - queue element type
Parameters:
name - identifier of the queue
klazz - concrete class for <E>
Returns:
a toolkit blocking queue
Throws:
IllegalArgumentException - if there is an existing queue with different capacity limit

getClusterInfo

ClusterInfo getClusterInfo()
Gets the ClusterInfo associated with the toolkit. If the implementation of the toolkit is not distributed in nature and not associated with a cluster, the implementation is free to either throw UnsupportedOperationException or return no-op implementations.

Returns:
the cluster info

getLock

ToolkitLock getLock(String name)
Get a reentrant toolkit write lock of the specified name. Multiple instances having the same name behave as same lock.

NOTE: This is different from the both the read/write locks obtained using ToolkitReadWriteLock.writeLock() and ToolkitReadWriteLock.readLock() from the read-write lock using getReadWriteLock(String) even with same name for the read-write lock.

Parameters:
name - identifier for the lock
Returns:
a toolkit lock

getReadWriteLock

ToolkitReadWriteLock getReadWriteLock(String name)
Get a reentrant toolkit read-write lock for the given name. Multiple instances having the same name behave as same lock.

NOTE: The lock returned from ToolkitReadWriteLock.writeLock() is different from the one using getLock(String) even with same name.

Parameters:
name - identifier for the lock
Returns:
a toolkit read-write lock

getNotifier

<E> ToolkitNotifier<E> getNotifier(String name,
                                   Class<E> klazz)
Gets or creates a ToolkitNotifier for the given name parameter.

Toolkit notifiers are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
E - notifier message type
Parameters:
name - identifier for the notifier
klazz - concrete class for <E>
Returns:
a toolkit notifier

getAtomicLong

ToolkitAtomicLong getAtomicLong(String name)
Returns a ToolkitAtomicLong for the given name parameter.

Toolkit atomic longs are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Parameters:
name - identifier for the AtomicLong
Returns:
a toolkit atomic long

getBarrier

ToolkitBarrier getBarrier(String name,
                          int parties)
Returns a ToolkitBarrier for the given name and specified parties.

If the barrier already exists with the same name and parties then it is returned. If it doesn't exist then it is created and registered. If the toolkit barrier already exists but has a different parties then IllegalArgumentException is thrown.

Toolkit barriers are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Parameters:
name - identifier for the toolkit barrier
parties - the parties involved in the barrier
Returns:
a toolkit barrier
Throws:
IllegalArgumentException - if there is an existing barrier with different number of parties with same name
IllegalArgumentException - if parties is less than 1

fireOperatorEvent

void fireOperatorEvent(OperatorEventLevel level,
                       String applicationName,
                       String eventMessage)
Fires an application specific Operator Event with the specified OperatorEventLevel and eventMessage.

Parameters:
level - level of the operator event
applicationName - name of the application which is firing the event
eventMessage - message content of the event

getSortedSet

<E extends Comparable<? super E>> ToolkitSortedSet<E> getSortedSet(String name,
                                                                   Class<E> klazz)
Returns an already created ToolkitSortedSet if one exists for the given name parameter, otherwise creates one and returns it. All elements inserted into the set must implement the Comparable interface.

Toolkit sorted sets are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
E - set element type
Parameters:
name - identifier for the sorted set
klazz - concrete class for <E>
Returns:
a toolkit sorted set

getSet

<E> ToolkitSet<E> getSet(String name,
                         Class<E> klazz)
Returns an already created ToolkitSet if one exists for the given name parameter, otherwise creates one and returns it.

Toolkit sets are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
E - set element type
Parameters:
name - name of the set
klazz - concrete class for <E>
Returns:
a toolkit set

getCache

<V> ToolkitCache<String,V> getCache(String name,
                                    Configuration configuration,
                                    Class<V> klazz)
Returns an already created ToolkitCache if one exists for the given name parameter, otherwise creates one using the configuration parameter and returns it. Subsequent calls with same name will return same cache. The configuration parameter can take various config. Keys in the mapping can take values declared in ToolkitConfigFields or ToolkitConfigFields. Refer to getStore(String, Configuration, Class) for behavior of various key-value store config fields. Behavior of the other cache configs are detailed in below table:
Configuration Field Default Value Instance exists in Cluster already Instance does NOT exist in Cluster yet
value passed in config value NOT passed in config value passed in config value NOT passed in config
MAX_TTI_SECONDS 0 IllegalArgumentException on mismatch Use existing value Use value passed in config Use default value
MAX_TTL_SECONDS 0 IllegalArgumentException on mismatch Use existing value Use value passed in config Use default value
MAX_TOTAL_COUNT 0 IllegalArgumentException on mismatch Use existing value Use value passed in config Use default value
PINNING_STORE NONE IllegalArgumentException on mismatch Use existing value Use value passed in config Use default value

Toolkit caches are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
V - cache value type
Parameters:
name - identifier for the cache
configuration - configuration with which the cache is to be created
klazz - concrete class for <V>
Returns:
a toolkit cache

getCache

<V> ToolkitCache<String,V> getCache(String name,
                                    Class<V> klazz)
Returns an already created ToolkitCache if one exists for the given name, otherwise creates one and returns it. It uses a default config and is effectively same as below:
 public ToolkitCache getCache(String name) {
   return getCache(name, new ToolkitCacheConfigBuilder().build());
 }
 

Toolkit caches are Destroyable and can be destroyed. Consult the class level docs for more info on behavior regarding destroy.

Implementations may choose to use the concrete class references to help enforce type safety of the returned data structure. Users can pass null class references in order to disable any implementation specific type checking and thereby gain raw access to the data structure.

Type Parameters:
V - cache value type
Parameters:
name - identifier for the cache
klazz - concrete class for <V>
Returns:
a toolkit cache with default config

shutdown

void shutdown()
Shut down toolkit and release resources associated with the toolkit. Multiple calls do not have any effect and are ignored.


getFeature

<T extends ToolkitFeature> T getFeature(ToolkitFeatureType<T> type)
Returns the ToolkitFeature implementation identified by type associated with the Toolkit.

Parameters:
type - the type identifying the feature.
Returns:
returns the feature identified by type.
See Also:
ToolkitFeatureType


Copyright © 2014 Terracotta, Inc.. All Rights Reserved.