Package com.yahoo.config.subscription

Class ConfigSubscriber

    • Field Detail

      • subscriptionHandles

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

    • 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 running locally. It can also be changed by setting VESPA_CONFIG_SOURCES.

    • Method Detail

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

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

      • nextConfig

        @Deprecated
public boolean nextConfig()
        Deprecated.

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

      • nextConfig

        @Deprecated
public boolean nextConfig​(long timeoutMillis)
        Deprecated.

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

      • nextGeneration

        @Deprecated
public boolean nextGeneration()
        Deprecated.

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

      • nextGeneration

        @Deprecated
public boolean nextGeneration​(long timeoutMillis)
        Deprecated.

      • 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

      • 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

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

      • 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