Package com.yahoo.config.subscription

Class ConfigSubscriber

java.lang.Object

com.yahoo.config.subscription.ConfigSubscriber

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

GenericConfigSubscriber

public class ConfigSubscriber
extends java.lang.Object
implements java.lang.AutoCloseable

Used for subscribing to one or more configs. Can optionally be given a ConfigSource for the configs that will be used when subscribe(Class, String) is called. subscribe(Class, String) on the configs needed, call nextConfig(long) and get the config from the ConfigHandle which subscribe(Class, String) returned.

Author:

Vegard Havdal

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ConfigSubscriber.SingleSubscriber<T extends com.yahoo.config.ConfigInstance>	Convenience interface for clients who only subscribe to one config.
protected static class	ConfigSubscriber.State	The states of the subscriber.

Field Summary

Fields

Modifier and Type	Field	Description
protected java.util.Map<ConfigSourceSet,JRTConfigRequester>	requesters	Reuse requesters for equal source sets, limit number if many subscriptions.
protected java.util.List<ConfigHandle<? extends com.yahoo.config.ConfigInstance>>	subscriptionHandles

Constructor Summary

Constructors

Constructor	Description
ConfigSubscriber()	Constructs a new subscriber.
ConfigSubscriber(ConfigSource source)	Constructs a new subscriber with the given source.

Method Summary

Modifier and Type	Method	Description
protected void	checkStateBeforeSubscribe()
void	close()	Closes all open ConfigSubscriptions
protected void	closeRequesters()	Closes all open requesters
protected void	finalize()	Finalizer to ensure that we do not leak resources on reconfig.
long	getGeneration()	The current generation of configs known by this subscriber.
ConfigSource	getSource()	The source used by this subscriber.
boolean	isClosed()
boolean	isInternalRedeploy()	Whether the current config generation received by this was due to a system-internal redeploy, not an application package change
boolean	nextConfig()	Use this for waiting for a new config that has changed.
boolean	nextConfig(long timeoutMillis)	Use this for waiting for a new config that has changed, with the given timeout.
boolean	nextGeneration()	Use this for waiting for a new config generation.
boolean	nextGeneration(long timeoutMillis)	Use this for waiting for a new config generation, with the given timeout Returns true if: It is the first time nextGeneration() is called on this subscriber, and the framework has fetched config for all subscriptions.
void	reload(long generation)	Sets all subscriptions under this subscriber to have the given generation.
java.util.Map<ConfigSourceSet,JRTConfigRequester>	requesters()	Implementation detail, do not use.
java.lang.Thread	startConfigThread(java.lang.Runnable runnable)	Convenience method to start a daemon thread called "Vespa config thread" with the given runnable.
protected ConfigSubscriber.State	state()
<T extends com.yahoo.config.ConfigInstance> ConfigHandle<T>	subscribe(ConfigSubscriber.SingleSubscriber<T> singleSubscriber, java.lang.Class<T> configClass, java.lang.String configId)	Use this convenience method if you only want to subscribe on one config, and want generic error handling.
<T extends com.yahoo.config.ConfigInstance> ConfigHandle<T>	subscribe(java.lang.Class<T> configClass, java.lang.String configId)	Subscribes on the given type of ConfigInstance with the given config id.
<T extends com.yahoo.config.ConfigInstance> ConfigHandle<T>	subscribe(java.lang.Class<T> configClass, java.lang.String configId, long timeoutMillis)	Subscribes on the given type of ConfigInstance with the given config id and subscribe timeout.
protected void	subscribeAndHandleErrors(ConfigSubscription<?> sub, ConfigKey<?> configKey, ConfigHandle<?> handle, TimingValues timingValues)
protected void	throwIfExceptionSet(ConfigSubscription<? extends com.yahoo.config.ConfigInstance> sub)	If a ConfigSubscription has its exception set, reset that field and throw it
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

subscriptionHandles

protected final java.util.List<ConfigHandle<? extends com.yahoo.config.ConfigInstance>> subscriptionHandles

requesters

protected java.util.Map<ConfigSourceSet,JRTConfigRequester> requesters

Reuse requesters for equal source sets, limit number if many subscriptions.

Constructor Detail

ConfigSubscriber

public ConfigSubscriber()

Constructs a new subscriber. The default Vespa network config source will be used, which is the address of a config proxy (part of vespa_base) running locally. It can also be changed by setting VESPA_CONFIG_SOURCES.

ConfigSubscriber

public ConfigSubscriber(ConfigSource source)

Constructs a new subscriber with the given source.

Parameters:

source - a ConfigSource that will be used when subscribe(Class, String) is called.

Method Detail

subscribe

public <T extends com.yahoo.config.ConfigInstance> ConfigHandle<T> subscribe(java.lang.Class<T> configClass,
                                                                             java.lang.String configId)

Subscribes on the given type of ConfigInstance with the given config id. The method blocks until the first config is ready to be fetched with nextConfig().

Parameters:

configClass - The class, typically generated from a def-file using config-class-plugin

configId - Identifies the service in vespa-services.xml, or null if you are using a local ConfigSource which does not use config id. Also supported: raw:, file:, dir: or jar: config id which addresses config locally in the same way.

Returns:

a ConfigHandle

subscribe

public <T extends com.yahoo.config.ConfigInstance> ConfigHandle<T> subscribe(java.lang.Class<T> configClass,
                                                                             java.lang.String configId,
                                                                             long timeoutMillis)

Subscribes on the given type of ConfigInstance with the given config id and subscribe timeout. The method blocks until the first config is ready to be fetched with nextConfig().

Parameters:

configClass - The class, typically generated from a def-file using config-class-plugin

configId - Identifies the service in vespa-services.xml, or possibly raw:, file:, dir: or jar: type config which addresses config locally.

timeoutMillis - The time to wait for a config to become available, in milliseconds

Returns:

a ConfigHandle

checkStateBeforeSubscribe

protected void checkStateBeforeSubscribe()

subscribeAndHandleErrors

protected void subscribeAndHandleErrors(ConfigSubscription<?> sub,
                                        ConfigKey<?> configKey,
                                        ConfigHandle<?> handle,
                                        TimingValues timingValues)

nextConfig

public boolean nextConfig()

Use this for waiting for a new config that has changed. Returns true if: It is the first time nextConfig() is called on this subscriber, and the framework has fetched config for all subscriptions. (Typically a first time config.) or All configs for the subscriber have a new generation since the last time nextConfig() was called, AND they have the same generation AND there is a change in config for at least one of the configs. (Typically calls for a reconfig.) You can check which configs are changed by calling ConfigHandle.isChanged() on the handle you got from subscribe(Class, String). If the call times out (timeout 1000 ms), no handle will have the changed flag set. You should not configure anything then.

Returns:

true if a config/reconfig of your system should happen

Throws:

ConfigInterruptedException - if thread performing this call interrupted.

nextConfig

public boolean nextConfig(long timeoutMillis)

Use this for waiting for a new config that has changed, with the given timeout. Returns true if: It is the first time nextConfig() is called on this subscriber, and the framework has fetched config for all subscriptions. (Typically a first time config.) or All configs for the subscriber have a new generation since the last time nextConfig() was called, AND they have the same generation AND there is a change in config for at least one of the configs. (Typically calls for a reconfig.) You can check which configs are changed by calling ConfigHandle.isChanged() on the handle you got from subscribe(Class, String). If the call times out, no handle will have the changed flag set. You should not configure anything then.

Parameters:

timeoutMillis - timeout in milliseconds

Returns:

true if a config/reconfig of your system should happen

Throws:

ConfigInterruptedException - if thread performing this call interrupted.

nextGeneration

public boolean nextGeneration()

Use this for waiting for a new config generation. Returns true if: It is the first time nextGeneration() is called on this subscriber, and the framework has fetched config for all subscriptions. (Typically a first time config.) or All configs for the subscriber have a new generation since the last time nextGeneration() was called, AND they have the same generation. Note that none of the configs have to be changed, but they might be. You can check which configs are changed by calling ConfigHandle.isChanged() on the handle you got from subscribe(Class, String). If the call times out (timeout 1000 ms), no handle will have the changed flag set. You should not configure anything then.

Returns:

true if generations for all configs have been updated.

Throws:

ConfigInterruptedException - if thread performing this call interrupted.

nextGeneration

public boolean nextGeneration(long timeoutMillis)

Use this for waiting for a new config generation, with the given timeout Returns true if: It is the first time nextGeneration() is called on this subscriber, and the framework has fetched config for all subscriptions. (Typically a first time config.) or All configs for the subscriber have a new generation since the last time nextGeneration() was called, AND they have the same generation. Note that none of the configs have to be changed, but they might be. You can check which configs are changed by calling ConfigHandle.isChanged() on the handle you got from subscribe(Class, String). If the call times out (timeout 1000 ms), no handle will have the changed flag set. You should not configure anything then.

Parameters:

timeoutMillis - timeout in milliseconds

Returns:

true if generations for all configs have been updated.

Throws:

ConfigInterruptedException - if thread performing this call interrupted.

throwIfExceptionSet

protected void throwIfExceptionSet(ConfigSubscription<? extends com.yahoo.config.ConfigInstance> sub)

If a ConfigSubscription has its exception set, reset that field and throw it

Parameters:

sub - ConfigSubscription

close

public void close()

Closes all open ConfigSubscriptions

Specified by:

close in interface java.lang.AutoCloseable

closeRequesters

protected void closeRequesters()

Closes all open requesters

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

startConfigThread

public java.lang.Thread startConfigThread(java.lang.Runnable runnable)

Convenience method to start a daemon thread called "Vespa config thread" with the given runnable. If you want the runnable to handle a ConfigSubscriber or ConfigHandle you have declared locally outside, declare them as final to make it work.

Parameters:

runnable - a class implementing Runnable

Returns:

the newly started thread

state

protected ConfigSubscriber.State state()

reload

public void reload(long generation)

Sets all subscriptions under this subscriber to have the given generation. This is intended for testing, to emulate a reload-config operation.

Parameters:

generation - a generation number

getSource

public ConfigSource getSource()

The source used by this subscriber.

Returns:

the ConfigSource used by this subscriber

requesters

public java.util.Map<ConfigSourceSet,JRTConfigRequester> requesters()

Implementation detail, do not use.

Returns:

requesters

isClosed

public boolean isClosed()

subscribe

public <T extends com.yahoo.config.ConfigInstance> ConfigHandle<T> subscribe(ConfigSubscriber.SingleSubscriber<T> singleSubscriber,
                                                                             java.lang.Class<T> configClass,
                                                                             java.lang.String configId)

Use this convenience method if you only want to subscribe on one config, and want generic error handling. Implement ConfigSubscriber.SingleSubscriber and pass to this method. You will get initial config, and a config thread will be started. The method will throw in your thread if initial configuration fails, and the config thread will print a generic error message (but continue) if it fails thereafter. The config thread will stop if you close() this ConfigSubscriber.

Type Parameters:

T - ConfigInstance type

Parameters:

singleSubscriber - The object to receive config

configClass - The class, typically generated from a def-file using config-class-plugin

configId - Identifies the service in vespa-services.xml

Returns:

The handle of the config

See Also:

startConfigThread(Runnable)

getGeneration

public long getGeneration()

The current generation of configs known by this subscriber.

Returns:

the current generation of configs known by this subscriber

isInternalRedeploy

public boolean isInternalRedeploy()

Whether the current config generation received by this was due to a system-internal redeploy, not an application package change

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalizer to ensure that we do not leak resources on reconfig. Though finalizers are bad, this is not a performance critical object as it will be deconstructed typically container reconfig.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable