eu.erasmuswithoutpaper.registryclient

Class ClientImplOptions

java.lang.Object

eu.erasmuswithoutpaper.registryclient.ClientImplOptions

public class ClientImplOptions
extends Object

Options passed to ClientImpl on construction.

Since:

1.0.0

Constructor Summary

Constructors

Constructor and Description
ClientImplOptions() Create a new set of options, initialized with default values.

Method Summary

Modifier and Type	Method and Description
boolean	getAutoRefreshing() Deprecated. As of release 1.2.0, replaced by isAutoRefreshing().
CatalogueFetcher	getCatalogueFetcher()
long	getMaxAcceptableStaleness()
long	getMinTimeBetweenQueries()
Map<String,byte[]>	getPersistentCacheMap()
Map<String,byte[]>	getPersistentCacheProvider() Deprecated. As of release 1.4.0, replaced by getPersistentCacheMap().
long	getStalenessWarningThreshold() Return the minimum staleness of the catalogue, above which ClientImpl will begin to report warning-level messages in its logs.
long	getTimeBetweenRetries()
boolean	isAutoRefreshing()
ClientImplOptions	setAutoRefreshing(boolean autoRefreshing) Set auto-refreshing on or off.
ClientImplOptions	setCatalogueFetcher(CatalogueFetcher catalogueFetcher) Tell ClientImpl to use a custom CatalogueFetcher.
ClientImplOptions	setMaxAcceptableStaleness(long milliseconds) Set a limit on maximum allowed staleness of the used catalogue.
ClientImplOptions	setMinTimeBetweenQueries(long milliseconds) Set a minimum time between subsequent auto-refresh queries.
ClientImplOptions	setPersistentCacheMap(Map<String,byte[]> persistentCacheMap) Tell ClientImpl to use a given map as persistent cache between its subsequent instantiations.
ClientImplOptions	setTimeBetweenRetries(long milliseconds) Set a time between query retries, when no valid response was received.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClientImplOptions

public ClientImplOptions()

Create a new set of options, initialized with default values.

Use set* methods to change the defaults. Default values are mentioned in the documentation of each method. Note, that each of the set* methods returns this, to enable setter chaining.

Method Detail

getAutoRefreshing

@Deprecated
public boolean getAutoRefreshing()

Deprecated. As of release 1.2.0, replaced by isAutoRefreshing().

Returns:

Same as isAutoRefreshing().

getCatalogueFetcher

public CatalogueFetcher getCatalogueFetcher()

Returns:

The CatalogueFetcher instance which will be used by the client. See setCatalogueFetcher(CatalogueFetcher).

getMaxAcceptableStaleness

public long getMaxAcceptableStaleness()

Returns:

The maximum staleness to be tolerated. See setMaxAcceptableStaleness(long).

getMinTimeBetweenQueries

public long getMinTimeBetweenQueries()

Returns:

The minimum time between Registry queries. See setMinTimeBetweenQueries(long).

getPersistentCacheMap

public Map<String,byte[]> getPersistentCacheMap()

Returns:

The cache instance to be used. See setPersistentCacheMap(Map).

Since:

1.4.0

getPersistentCacheProvider

@Deprecated
public Map<String,byte[]> getPersistentCacheProvider()

Deprecated. As of release 1.4.0, replaced by getPersistentCacheMap().

Returns:

The cache instance to be used. See setPersistentCacheMap(Map).

getStalenessWarningThreshold

public long getStalenessWarningThreshold()

Return the minimum staleness of the catalogue, above which ClientImpl will begin to report warning-level messages in its logs.

Returns:

milliseconds

getTimeBetweenRetries

public long getTimeBetweenRetries()

Returns:

Time to wait between retries when no valid result is receives. See setTimeBetweenRetries(long).

isAutoRefreshing

public boolean isAutoRefreshing()

Returns:

The value previously set via setAutoRefreshing(boolean).

Since:

1.2.0

setAutoRefreshing

public ClientImplOptions setAutoRefreshing(boolean autoRefreshing)

Set auto-refreshing on or off. Default is off (to avoid accidental "DoS attacks" on misconfiguration), but it is recommended to turn it on.

Once this option is turned on, ClientImpl will automatically call its ClientImpl.refresh() method whenever the currently held version of the catalogue document expires. This will usually be done in a separate background thread, but ClientImpl might also try to do this during the construction time, if it thinks it's needed.

Parameters:

autoRefreshing - true to turn auto-refreshing on, false to turn it off.

Returns:

This object.

setCatalogueFetcher

public ClientImplOptions setCatalogueFetcher(CatalogueFetcher catalogueFetcher)

Tell ClientImpl to use a custom CatalogueFetcher.

By default, it will use a DefaultCatalogueFetcher instance for fetching the catalogue files from the Registry Service. You might want to tweak this is some situations (for example when running unit-tests).

Parameters:

catalogueFetcher - CatalogueFetcher to use.

Returns:

This object.

setMaxAcceptableStaleness

public ClientImplOptions setMaxAcceptableStaleness(long milliseconds)

Set a limit on maximum allowed staleness of the used catalogue. Default is 5 days.

In general, if auto-refreshing is turned on, ClientImpl will always keep the internal copy of the catalogue up-to-date. However, if ClientImpl will not be able to fetch a fresh copy, then it will reuse the older (stale) copy of the catalogue. The amount of time which has passed since the internal copy has expired is defined as "catalogue staleness".

It is reasonable to to use a copy of a catalogue which is one or two hours stale, if - for some reason - we cannot retrieve the fresh copy. However, as the staleness grows, it becomes more dangerous to use such stale copy. Once the staleness reaches a certain limit, ClientImpl will start to throw RegistryClient.UnacceptableStalenessException exceptions. These are not checked exceptions, and they are not usually caught, so, most likely, they will cause your application to break. Note, that ClientImpl will attempt to warn you before this happens (see getStalenessWarningThreshold()).

Parameters:

milliseconds - the new value of acceptable staleness, in milliseconds.

Returns:

This object.

setMinTimeBetweenQueries

public ClientImplOptions setMinTimeBetweenQueries(long milliseconds)

Set a minimum time between subsequent auto-refresh queries. Default is 60 seconds. Usually there is no need to change this default. It is relevant only in unit-tests.

In auto-refreshing mode ClientImpl attempts to query the Registry Service as often as the Registry Service wishes. For example: If the Registry tells us to refresh in 15 minutes, then we will refresh in 15 minutes. However, if the Registry tells us to refresh in 1 second (which might be due to invalid CatalogueFetcher implementation), then ClientImpl will not listen to such suggestion, and use the value supplied here instead.

This option is relevant only in auto-refreshing mode. Manual calls to ClientImpl.refresh() will never be limited.

Parameters:

milliseconds - the minimum time between auto-refresh queries, in milliseconds.

Returns:

This object.

setPersistentCacheMap

public ClientImplOptions setPersistentCacheMap(Map<String,byte[]> persistentCacheMap)

Tell ClientImpl to use a given map as persistent cache between its subsequent instantiations. Default is null.

If given, ClientImpl will use this map to keep a persistent copy of the catalogue. It will load the catalogue from this cache during construction. If the loaded copy is fresh enough, then it may speed up the construction time and help you avoid RegistryClient.UnacceptableStalenessException exceptions. It is okay for this cache to be purged without notice, it is also okay for some elements to be removed once other stay. You should however take care that all of its keys are modifiable by ClientImpl only.

In most cases, supplying this object makes sense only if its data is persisted to a hard drive, or a similar "more persistent than usual" medium (otherwise you can simply keep ClientImpl in memory instead of destroying it between runs).

Parameters:

persistentCacheMap - a new map to use as cache.

Returns:

This object.

setTimeBetweenRetries

public ClientImplOptions setTimeBetweenRetries(long milliseconds)

Set a time between query retries, when no valid response was received. Default is 3 minutes.

This option is relevant only in auto-refreshing mode. If the catalogue cannot be retrieved for some reason, this is the time we will wait before we retry.

Parameters:

milliseconds - time, in milliseconds.

Returns:

This object.

toString

public String toString()

Overrides:

toString in class Object