|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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
.
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. |
|
|
getBlockingQueue(String name,
Class<E> klazz)
Get or create a toolkit blocking queue for the given name . |
|
|
getBlockingQueue(String name,
int capacity,
Class<E> klazz)
Get or create a toolkit blocking queue with a capacity limit for the given name . |
|
|
getCache(String name,
Class<V> klazz)
Returns an already created ToolkitCache if one exists for the given name , otherwise creates one and
returns it. |
|
|
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. |
|
|
getFeature(ToolkitFeatureType<T> type)
Returns the ToolkitFeature implementation identified by type associated with the
Toolkit . |
|
|
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 . |
|
|
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. |
|
|
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 . |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
getStore(String name,
Class<V> klazz)
Returns an already created ToolkitStore if one exists for the given name , otherwise creates one and
returns it. |
|
|
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 |
---|
<E> ToolkitList<E> getList(String name, Class<E> klazz)
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.
E
- list element typename
- identifier of the listklazz
- concrete class for <E>
<V> ToolkitStore<String,V> getStore(String name, Configuration configuration, Class<V> klazz)
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 mismatchUse existing value Use value passed in config Use default value CONCURRENCY 256 IllegalArgumentException
on mismatchUse 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 thereafterUse 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 thereafterUse 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 thereafterUse 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 thereafterUse 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 thereafterUse 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.
V
- store value typename
- identifier for the key-value storeconfiguration
- configuration with which the key-value store is to be createdklazz
- concrete class for <V>
<V> ToolkitStore<String,V> getStore(String name, Class<V> klazz)
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.
V
- store value typename
- identifier for the key-value storeklazz
- concrete class for <V>
<K,V> ToolkitMap<K,V> getMap(String name, Class<K> keyKlazz, Class<V> valueKlazz)
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.
K
- map key typeV
- map value typename
- identifier for the mapkeyKlazz
- concrete class for <K>
valueKlazz
- concrete class for <V>
<K extends Comparable<? super K>,V> ToolkitSortedMap<K,V> getSortedMap(String name, Class<K> keyKlazz, Class<V> valueKlazz)
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.
K
- map key typeV
- map value typename
- identifier for the mapkeyKlazz
- concrete class for <K>
valueKlazz
- concrete class for <V>
<E> ToolkitBlockingQueue<E> getBlockingQueue(String name, int capacity, Class<E> klazz)
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.
E
- queue element typename
- identifier for the queuecapacity
- the capacity limit for the queueklazz
- concrete class for <E>
IllegalArgumentException
- if there is an existing queue of same name
with a different capacity limit
IllegalArgumentException
- if capacity
is less than 1.<E> ToolkitBlockingQueue<E> getBlockingQueue(String name, Class<E> klazz)
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.
E
- queue element typename
- identifier of the queueklazz
- concrete class for <E>
IllegalArgumentException
- if there is an existing queue with different capacity limitClusterInfo getClusterInfo()
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.
ToolkitLock getLock(String name)
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.
name
- identifier for the lock
ToolkitReadWriteLock getReadWriteLock(String name)
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.
name
- identifier for the lock
<E> ToolkitNotifier<E> getNotifier(String name, Class<E> klazz)
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.
E
- notifier message typename
- identifier for the notifierklazz
- concrete class for <E>
ToolkitAtomicLong getAtomicLong(String name)
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.
name
- identifier for the AtomicLong
ToolkitBarrier getBarrier(String name, int parties)
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.
name
- identifier for the toolkit barrierparties
- the parties involved in the barrier
IllegalArgumentException
- if there is an existing barrier with different number of parties with same name
IllegalArgumentException
- if parties
is less than 1void fireOperatorEvent(OperatorEventLevel level, String applicationName, String eventMessage)
OperatorEventLevel
and eventMessage.
level
- level of the operator eventapplicationName
- name of the application which is firing the eventeventMessage
- message content of the event<E extends Comparable<? super E>> ToolkitSortedSet<E> getSortedSet(String name, Class<E> klazz)
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.
E
- set element typename
- identifier for the sorted setklazz
- concrete class for <E>
<E> ToolkitSet<E> getSet(String name, Class<E> klazz)
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.
E
- set element typename
- name of the setklazz
- concrete class for <E>
<V> ToolkitCache<String,V> getCache(String name, Configuration configuration, Class<V> klazz)
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 mismatchUse existing value Use value passed in config Use default value MAX_TTL_SECONDS 0 IllegalArgumentException
on mismatchUse existing value Use value passed in config Use default value MAX_TOTAL_COUNT 0 IllegalArgumentException
on mismatchUse existing value Use value passed in config Use default value PINNING_STORE NONE IllegalArgumentException
on mismatchUse 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.
V
- cache value typename
- identifier for the cacheconfiguration
- configuration with which the cache is to be createdklazz
- concrete class for <V>
<V> ToolkitCache<String,V> getCache(String name, Class<V> klazz)
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.
V
- cache value typename
- identifier for the cacheklazz
- concrete class for <V>
void shutdown()
<T extends ToolkitFeature> T getFeature(ToolkitFeatureType<T> type)
ToolkitFeature
implementation identified by type
associated with the
Toolkit
.
type
- the type identifying the feature.
type
.ToolkitFeatureType
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |