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(IDiscoveryEntity entity) Add a new entity into a cache.
void	add(String type, String name, List<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	create(String type, String name, List<UtlAddressDescriptor> descriptors) Create a discovery entity.
IDiscoveryEntity	get(String type, String name) Get an entity from the cache.
Object	getCacheLock() Get the object used to lock the discovery cache This method returns the object used to lock the 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.
XString	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.
void	open() Open the cache.
boolean	opened() Get if the cache has been opened.
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.

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.

Threading:

This method is safe for concurrent access by multiple threads.

getMaxEntityAge

short getMaxEntityAge()

Get the entity's max age.

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.

Threading:

This method is safe for concurrent access by multiple threads.

getMaxEsaLoss

short getMaxEsaLoss()

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

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.

Threading:

This method is safe for concurrent access by multiple threads.

getLocalMemberName

String getLocalMemberName()

Get the name of the local cache member.

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'.

Threading:

This method is safe for concurrent access by multiple threads.

getLocalMemberNameAsRaw

XString getLocalMemberNameAsRaw()

Get the name of the local cache member.

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'.

Threading:

This method is safe for concurrent access by multiple threads.

open

void open()
          throws EDiscoveryException

Open the cache.

This method opens the discovery cache. This method is automatically invoked when the cache is created (during DiscoveryCacheFactory.createCache(String, int)) unless the DiscoveryCacheFactory.FLG_NO_AUTOOPEN is specified to the method.

Throws:

EDiscoveryException

Threading:

This method is safe for concurrent access by multiple threads.

opened

boolean opened()

Get if the cache has been opened.

Returns:

This method returns true if and only if the open method was invoked and it completed successfully

Threading:

This method is safe for concurrent access by multiple threads.

addEventHandler

void addEventHandler(IDiscoveryCacheEventHandler eventHandler)

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

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

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.

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

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.

Threading:

This method is safe for concurrent access by multiple threads.

create

IDiscoveryEntity create(String type,
                        String name,
                        List<UtlAddressDescriptor> descriptors)

Create a discovery entity.

There are some situations in which a user of the discovery cache needs to know the object representing the entity that it is adding before it adds the entity to the cache. For example, in a situation when the caller wants to listen to a stream of events from the cache and filter the events for entities that it has added, the caller would need to create the entities first before adding them to the cache so that caller has the entity to filter at the time the addition method dispatches the addition event.

If the above semantics are not needed, then the user should add entities into the cache using add(String, String, List)

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.

Threading:

This method is safe for concurrent access by multiple threads.

add

void add(IDiscoveryEntity entity)

Add a new entity into a 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.

Parameters:

entity - The entity as created by create(String, String, List)

Throws:

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

ClassCastException - Thrown if this method is invoked using an entity not created by {#link #create}

Threading:

This method is safe for concurrent access by multiple threads.

add

void add(String type,
         String name,
         List<UtlAddressDescriptor> descriptors)

Add a new entity into a cache.

This method creates an entity using create(String, String, List) and then adds it to the cache using add(IDiscoveryEntity)

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.

Threading:

This method is safe for concurrent access by multiple threads.

get

IDiscoveryEntity get(String type,
                     String name)

Get an entity from the 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.

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.

Threading:

This method is safe for concurrent access by multiple threads.

remove

IDiscoveryEntity remove(String type,
                        String name)

Remove an entity from the 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.

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.

Threading:

This method is safe for concurrent access by multiple threads.

remove

boolean remove(IDiscoveryEntity entity)

Remove an entity from the cache.

This method finds and removes a specified entity from a discovery 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.

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.

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)

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.

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.

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).

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.

Threading:

This method is safe for concurrent access by multiple threads.

suspendAgeing

void suspendAgeing()

Suspend ageing of discovered entities.

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.

Throws:

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

resumeAgeing

void resumeAgeing()

Resume ageing of discovered entities.

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

Throws:

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

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.

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

Threading:

This method is safe for concurrent access by multiple threads.