com.neeve.discovery
Interface IDiscoveryCache

public interface IDiscoveryCache

Represents a discovery cache.

This is the core interface ia which a user accesses the discovery cache. The discovery cache contains information about all discovered entities. The user can query for entity information or register to be notified when the cache changes i.e. when new entities are discovered and/or when entities are removed.

Threading:

This class is not safe for concurrent access by multiple threads

Method Summary

void	add(String type, String name, List<com.neeve.util.UtlAddressDescriptor> descriptors) Add a new entity into a cache.
void	addEventHandler(IDiscoveryCacheEventHandler eventHandler) Add an event handler to a cache's event handler set.
void	close() Close the cache
boolean	closed() Get if the cache is closed
IDiscoveryEntity	get(String type, String name) Get an entity from the cache
Object	getCacheLock() Get the object used to lock the discovery cache
short	getInitWaitTime() Get the time that new cache members wait during construction for remote entities to be populated in its cache.
String	getLocalMemberName() Get the name of the local cache member.
com.neeve.raw.RawString	getLocalMemberNameAsRaw() Get the name of the local cache member.
short	getMaxEntityAge() Get the entity's max age.
short	getMaxEsaLoss() Get the maximum number of ESAs that can be lost for an entity to be deemed as expired.
Set<IDiscoveryEntity>	matches(String types) Returns all entities for a set of entity types.
Set<IDiscoveryEntity>	matches(String types, String names) Returns all entities of a specific type that match a wildcard based name pattern.
boolean	remove(IDiscoveryEntity entity) Remove an entity from the cache
IDiscoveryEntity	remove(String type, String name) Remove an entity from the cache
void	removeEventHandler(IDiscoveryCacheEventHandler eventHandler) Remove an event handler from a cache's event handler set.
void	resumeAgeing() Resume ageing of discovered entities
int	size() Get the number of entities in the cache
void	suspendAgeing() Suspend ageing of discovered entities

Method Detail

getInitWaitTime

short getInitWaitTime()

Get the time that new cache members wait during construction for remote entities to be populated in its cache.

Threading:

This method is safe for concurrent access by multiple threads.

Upon construction, cache members solicit entity advertisements from remote members to populate its local cache. The initial wait time is the time that the cache contructor will sleep waiting for remote entities to be populated in the local cache.

The default value for this parameter is 5 seconds. It can be changed via the initWaitTime property in the cache descriptor e.g. mcast:224.0.1.200:4090&initWaitTime=10 would increase the initial wait time to 10 seconds.

getMaxEntityAge

short getMaxEntityAge()

Get the entity's max age.

Threading:

This method is safe for concurrent access by multiple threads.

This returns the maximum age associated with each entity created by the local cache member. See IDiscoveryEntity.getMaxAge() for a description on the role played by an entity's age in its lifecycle management.

The default value for this parameter is 15 seconds. It can be changed via the maxEntityAge property in the cache descriptor. For example, mcast:224.0.1.200:4090&maxEntityAge=20 would increase the an entity's maximum age to 20.

This parameter works hand in hand with the maxESALoss parameter. The cache uses both these parameters to determine how often to transmit ESAs.

getMaxEsaLoss

short getMaxEsaLoss()

Get the maximum number of ESAs that can be lost for an entity to be deemed as expired.

Threading:

This method is safe for concurrent access by multiple threads.

A cache member manages the lifecyle of discovered entities via its maximum age. The member uses a timer to periodically increment the entity's age. When the age reaches the maximum age, it is considered expired and removed from the cache. Entity owners preempt expiry of an entity by continually broadcasting ESAs for the entity. The ESAs cause the entity's age to be reset in the remote caches.

An entity owner determines how often to broadcast ESAs using the maxEntityAge and maxESALoss parameters i.e. ESAs are broadcast every maxEntityAge / maxESALoss seconds.

The default value for this parameter is 3. It can be changed via the maxEsaLoss property in the cache descriptor. For example, mcast:224.0.1.200:4090&maxEsaLoss=5 would increase the ESA loss tolerance to 5.

getLocalMemberName

String getLocalMemberName()

Get the name of the local cache member.

Threading:

This method is safe for concurrent access by multiple threads.

Each discovery cache member is uniquely identified by a name. The member name is used to identify entity ownership.

By default, each member is uniquely identified by a UUID. However, the user can override the use of UUIDs for identification through the use of the memberName property in the cache descriptor. For example, mcast:224.0.1.200:4090&memberName=m1 would identify the cache member opening a cache using the above descriptor as 'm1'.

getLocalMemberNameAsRaw

com.neeve.raw.RawString getLocalMemberNameAsRaw()

Get the name of the local cache member.

Threading:

This method is safe for concurrent access by multiple threads.

Each discovery cache member is uniquely identified by a name. The member name is used to identify entity ownership.

By default, each member is uniquely identified by a UUID. However, the user can override the use of UUIDs for identification through the use of the memberName property in the cache descriptor. For example, mcast:224.0.1.200:4090&memberName=m1 would identify the cache member opening a cache using the above descriptor as 'm1'.

addEventHandler

void addEventHandler(IDiscoveryCacheEventHandler eventHandler)

Add an event handler to a cache's event handler set.

Throws:

IllegalArgumentException - Thrown if the specified event handler is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

The discovery cache dispatches cache events to all registered event handlers. This method can be called repeatedly with the same event handler.

Threading:

This method is safe for concurrent access by multiple threads.

removeEventHandler

void removeEventHandler(IDiscoveryCacheEventHandler eventHandler)

Remove an event handler from a cache's event handler set.

Throws:

IllegalArgumentException - Thrown if the specified event handler is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

Threading:

This method is safe for concurrent access by multiple threads.

getCacheLock

Object getCacheLock()

Get the object used to lock the discovery cache

Threading:

This method is safe for concurrent access by multiple threads.

This method returns the object used to lock the cache. It is gauranteed that the cache wil not be modified as long as the user synchronizes on this lock object.

add

void add(String type,
         String name,
         List<com.neeve.util.UtlAddressDescriptor> descriptors)

Add a new entity into a cache.

Parameters:

type - The entity's type.

name - The entity's name.

descriptors - The entity's address descriptors

Throws:

IllegalArgumentException - Thrown if any of the specified arguments is null or the descriptor list is empty.

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method adds an entity into the discovery cache. If an entity with the same name and type already exists in the cache, the existing entity will be replaced.

This method will cause an entity addition event to be dispatched to the registered event handlers. The event data will reflect whether the addition caused an existing entity to be replaced.

Threading:

This method is safe for concurrent access by multiple threads.

get

IDiscoveryEntity get(String type,
                     String name)

Get an entity from the cache

Parameters:

type - The entity type

name - The entity name

Returns:

Returns the found entity or null if no entity of the specified type and name is present in the cache.

Throws:

IllegalArgumentException - Thrown if any of the method arguments is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method retrieves an entity of the specified type and name from a cache. A value of null is returned if no entity of the specified type and name exists in the cache.

Threading:

This method is safe for concurrent access by multiple threads.

remove

IDiscoveryEntity remove(String type,
                        String name)

Remove an entity from the cache

Parameters:

type - The entity type

name - The entity name

Returns:

Returns the found entity or null if no entity of the specified type and name is present in the cache.

Throws:

IllegalArgumentException - Thrown if any of the method arguments is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method removes an entity of the specified type and name from a cache. The removal of an entity will cause an entity removal event to be dispatched to registered event handlers. No event is dispatched if an entity was not removed i.e. if this method returns null.

Threading:

This method is safe for concurrent access by multiple threads.

remove

boolean remove(IDiscoveryEntity entity)

Remove an entity from the cache

Parameters:

entity - The entity to remove

Returns:

Returns true if the entity was found and removed and false otherwise.

Throws:

IllegalArgumentException - Thrown if any of the method arguments is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method finds and removes a specified entity from a discovery cache.

Threading:

This method is safe for concurrent access by multiple threads.

matches

Set<IDiscoveryEntity> matches(String types,
                              String names)

Returns all entities of a specific type that match a wildcard based name pattern.

Parameters:

types - The entity type. This parameter can be a literal type name or contain wilcards to match a set of entity types. See Hstr for the wildcard format. This parameter cannot contain level wildcards.

names - The name pattern to match. The name pattern can be a literal entity name of contain wilcards to match a set of entities. See Hstr for the wildcard pattern format.

Throws:

IllegalArgumentException - Thrown if any of the method arguments is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method returns the set of entities of a given type whose names match a name pattern. See Hstr for the pattern format.

The returned set is not related to the underlying storage used by the cache. Therefore, any modification of the set has no impact on the cache (and vice versa)

Threading:

This method is safe for concurrent access by multiple threads.

matches

Set<IDiscoveryEntity> matches(String types)

Returns all entities for a set of entity types.

Parameters:

types - The type pattern to match. This parameter can be a literal type name or contain wildcards to match a set of entity types. See Hstr for the wildcard pattern format. This parameter can contain level wilcard. For example, "..." will return all entities of all types.

Throws:

IllegalArgumentException - Thrown if any of the method arguments is null.

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method returns the set of entities of a given type. The returned set is not related to the underlying storage used by the cache. Therefore, any modification of the set has no impact on the cache (and vice versa).

Threading:

This method is safe for concurrent access by multiple threads.

suspendAgeing

void suspendAgeing()

Suspend ageing of discovered entities

Throws:

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method causes ageing of discovered entities to be suspended. Ageing is resumed on a subsequent call to resumeAgeing(). Discovered entities will not be expired while ageing is suspended.

resumeAgeing

void resumeAgeing()

Resume ageing of discovered entities

Throws:

IllegalStateException - Thrown if this method is invoked on a closed cache.

This method causes suspended ageing of entities triggered by the suspendAgeing() method to be resumed.

size

int size()

Get the number of entities in the cache

Throws:

IllegalStateException - Thrown if this method is invoked on a closed cache.

closed

boolean closed()

Get if the cache is closed

Threading:

This method is safe for concurrent access by multiple threads.

close

void close()

Close the cache

Threading:

This method is safe for concurrent access by multiple threads.

This method closes the discovery cache. This method should be the last call made to the cache.