Package com.yahoo.config.subscription

Class ConfigSubscriber

java.lang.Object
com.yahoo.config.subscription.ConfigSubscriber
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
GenericConfigSubscriber
public class ConfigSubscriber extends Object implements 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(boolean) and get the config from the ConfigHandle which subscribe(Class, String) returned.
Author:
Vegard Havdal

  • Field Details

    • subscriptionHandles

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

  • Constructor Details

    • ConfigSubscriber

      public ConfigSubscriber()
      Constructs a new subscriber. The default Vespa network config source will be used, which is the address of a config proxy 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 Details

    • subscribe

      public <T extends com.yahoo.config.ConfigInstance> ConfigHandle<T> subscribe(Class<T> configClass, 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(boolean).
      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(Class<T> configClass, 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(boolean).
      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(boolean isInitializing)
      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.
      Parameters:
      isInitializing - true if this the config is needed to create the initial configuration for the caller, false if this is for reconfiguration
      Returns:
      true if a config/reconfig of your system should happen
      Throws:
      ConfigInterruptedException - if thread performing this call interrupted.
      SubscriberClosedException - if subscriber is closed

    • nextConfig

      public boolean nextConfig(long timeoutMillis, boolean isInitializing)
      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
      isInitializing - true if this the config is needed to create the initial configuration for the caller, false if this is for reconfiguration
      Returns:
      true if a config/reconfig of your system should happen
      Throws:
      ConfigInterruptedException - if thread performing this call interrupted.
      SubscriberClosedException - if subscriber is closed

    • nextGeneration

      public boolean nextGeneration(boolean isInitializing)
      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.
      Parameters:
      isInitializing - true if this the next generation is needed to create the initial configuration for the caller, false if this is for reconfiguration
      Returns:
      true if generations for all configs have been updated.
      Throws:
      ConfigInterruptedException - if thread performing this call interrupted.
      SubscriberClosedException - if subscriber is closed

    • nextGeneration

      public boolean nextGeneration(long timeoutMillis, boolean isInitializing)
      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
      isInitializing - true if this the next generation is needed to create the initial configuration for the caller, false if this is for reconfiguration
      Returns:
      true if generations for all configs have been updated.
      Throws:
      ConfigInterruptedException - if thread performing this call interrupted.
      SubscriberClosedException - if subscriber is closed

    • 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 AutoCloseable

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • startConfigThread

      public Thread startConfigThread(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

    • isClosed

      public boolean isClosed()

    • subscribe

      public <T extends com.yahoo.config.ConfigInstance> ConfigHandle<T> subscribe(ConfigSubscriber.SingleSubscriber<T> singleSubscriber, Class<T> configClass, String configId)
      Convenience method that can be used if you only want to subscribe to one config, and want generic error handling. Implement ConfigSubscriber.SingleSubscriber and pass it 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:

    • getGeneration

      public long getGeneration()
      The current generation of configs known by this subscriber.
      Returns:
      the current generation of configs known by this subscriber

    • finalize

      protected void finalize() throws 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 Object
      Throws:
      Throwable