Package io.joynr.arbitration

Class DiscoveryQos

  • public class DiscoveryQos
extends Object
    Storage class to pass all settings to an arbitrator defining the strategy and conditions for provider arbitration.

    • Constructor Detail

      • DiscoveryQos

        public DiscoveryQos()

      • DiscoveryQos

        public DiscoveryQos​(long discoveryTimeout,
                    ArbitrationStrategy arbitrationStrategy,
                    long cacheMaxAge)
        Parameters:
        discoveryTimeout - Timeout for rpc calls to wait for arbitration to finish.
        arbitrationStrategy - Strategy for choosing the appropriate provider from the list returned by the capabilities directory
        cacheMaxAge - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.

      • DiscoveryQos

        public DiscoveryQos​(long discoveryTimeout,
                    ArbitrationStrategyFunction arbitrationStrategyFunction,
                    long cacheMaxAge)
        Parameters:
        discoveryTimeout - Timeout for rpc calls to wait for arbitration to finish.
        arbitrationStrategyFunction - function that chooses the appropriate provider from the list returned by the capabilities directory
        cacheMaxAge - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.

      • DiscoveryQos

        public DiscoveryQos​(long discoveryTimeout,
                    ArbitrationStrategy arbitrationStrategy,
                    long cacheMaxAge,
                    DiscoveryScope discoveryScope)
        Parameters:
        discoveryTimeout - Timeout for rpc calls to wait for arbitration to finish.
        arbitrationStrategy - Strategy for choosing the appropriate provider from the list returned by the capabilities directory
        cacheMaxAge - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.
        discoveryScope - determines where the discovery process will look for matching providers
        • LOCAL_ONLY: only locally registered providers will be considered.
        • LOCAL_THEN_GLOBAL locally registered providers are preferred. When none is found, the global providers are included in search results.
        • LOCAL_AND_GLOBAL: all providers registered locally, and query results from the gobal directory are combined and returned.
        • GLOBAL_ONLY only returns providers that are found in the global directory.

      • DiscoveryQos

        public DiscoveryQos​(long discoveryTimeout,
                    long retryIntervalMs,
                    ArbitrationStrategy arbitrationStrategy,
                    long cacheMaxAge,
                    DiscoveryScope discoveryScope)
        Parameters:
        discoveryTimeout - Timeout for rpc calls to wait for arbitration to finish.
        retryIntervalMs - Lookups for the arbitration will be repeated after this time interval if they were not successful. The actual delay may be longer, as there is a system-wide minimum delay (see ConfigurableMessagingSettings.PROPERTY_DISCOVERY_MINIMUM_RETRY_INTERVAL_MS).
        arbitrationStrategy - Strategy for choosing the appropriate provider from the list returned by the capabilities directory
        cacheMaxAge - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.
        discoveryScope - determines where the discovery process will look for matching providers
        • LOCAL_ONLY: only locally registered providers will be considered.
        • LOCAL_THEN_GLOBAL locally registered providers are preferred. When none is found, the global providers are included in search results.
        • LOCAL_AND_GLOBAL: all providers registered locally, and query results from the gobal directory are combined and returned.
        • GLOBAL_ONLY only returns providers that are found in the global directory.

      • DiscoveryQos

        public DiscoveryQos​(long discoveryTimeout,
                    ArbitrationStrategyFunction arbitrationStrategyFunction,
                    long cacheMaxAge,
                    DiscoveryScope discoveryScope)
        Parameters:
        discoveryTimeout - Timeout for rpc calls to wait for arbitration to finish.
        arbitrationStrategyFunction - function that chooses the appropriate provider from the list returned by the capabilities directory
        cacheMaxAge - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.
        discoveryScope - determines where the discovery process will look for matching providers
        • LOCAL_ONLY: only locally registered providers will be considered.
        • LOCAL_THEN_GLOBAL locally registered providers are preferred. When none is found, the global providers are included in search results.
        • LOCAL_AND_GLOBAL: all providers registered locally, and query results from the gobal directory are combined and returned.
        • GLOBAL_ONLY only returns providers that are found in the global directory.

      • DiscoveryQos

        public DiscoveryQos​(long discoveryTimeout,
                    long retryIntervalMs,
                    ArbitrationStrategyFunction arbitrationStrategyFunction,
                    long cacheMaxAge,
                    DiscoveryScope discoveryScope)
        Parameters:
        discoveryTimeout - Timeout for rpc calls to wait for arbitration to finish.
        retryIntervalMs - Lookups for the arbitration will be repeated after this time interval if they were not successful. The actual delay may be longer, as there is a system-wide minimum delay (see ConfigurableMessagingSettings.PROPERTY_DISCOVERY_MINIMUM_RETRY_INTERVAL_MS).
        arbitrationStrategyFunction - function that chooses the appropriate provider from the list returned by the capabilities directory
        cacheMaxAge - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.
        discoveryScope - determines where the discovery process will look for matching providers
        • LOCAL_ONLY: only locally registered providers will be considered.
        • LOCAL_THEN_GLOBAL locally registered providers are preferred. When none is found, the global providers are included in search results.
        • LOCAL_AND_GLOBAL: all providers registered locally, and query results from the gobal directory are combined and returned.
        • GLOBAL_ONLY only returns providers that are found in the global directory.

    • Method Detail

      • setArbitrationStrategy

        public void setArbitrationStrategy​(ArbitrationStrategy arbitrationStrategy)
        The discovery process outputs a list of matching providers. The arbitration strategy then chooses one or more of them to be used by the proxy.
        Parameters:
        arbitrationStrategy - Defines the strategy used to choose the "best" provider.

      • getArbitrationStrategy

        public ArbitrationStrategy getArbitrationStrategy()
        The discovery process outputs a list of matching providers. The arbitration strategy then chooses one or more of them to be used by the proxy.
        Returns:
        the arbitration strategy used to pick the "best" provider of the list of matching providers

      • setDiscoveryTimeoutMs

        public void setDiscoveryTimeoutMs​(long discoveryTimeoutMs)
        As soon as the arbitration QoS is set on the proxy builder, discovery of suitable providers is triggered. If the discovery process does not find matching providers within the arbitration timeout duration it will be terminated and you will get an arbitration exception.
        Parameters:
        discoveryTimeoutMs - Sets the amount of time the arbitrator keeps trying to find a suitable provider. The arbitration lookup might happen multiple times during this time span.

      • getDiscoveryTimeoutMs

        public long getDiscoveryTimeoutMs()
        As soon as the arbitration QoS is set on the proxy builder, discovery of suitable providers is triggered. If the discovery process does not find matching providers within the arbitration timeout duration it will be terminated and you will get an arbitration exception.
        Returns:
        the duration used to discover matching providers

      • addCustomParameter

        public void addCustomParameter​(String key,
                               String value)
        addCustomParameter allows to add special parameters to the DiscoveryQos which will be used only by some strategies.
        Parameters:
        key - String to identify the arbitration parameter
        value - Any object used by the arbitrator to choose a provider.

      • getCustomParameter

        public Object getCustomParameter​(String key)
        getCustomParameter returns the parameters previously specified by addParameter
        Parameters:
        key - key to identify the custom parameter
        Returns:
        Returns the value to which the specified key is mapped, or null if the map of additional parameters contains no mapping for the key

      • getCacheMaxAgeMs

        public long getCacheMaxAgeMs()
        Provider entries in the global capabilities directory are cached locally. Discovery will consider entries in this cache valid if they are younger than the max age of cached providers as defined in the QoS. All valid entries will be processed by the arbitrator when searching for and arbitrating the "best" matching provider.

        NOTE: Valid cache entries might prevent triggering a lookup in the global capabilities directory. Therefore, providers registered with the global capabilities after the last lookup and before the cacheMaxAge expires will not be discovered.

        Returns:
        the maximum age of locally cached provider entries to be used during discovery and arbitration before refreshing from the global directory

      • setCacheMaxAgeMs

        public void setCacheMaxAgeMs​(long cacheMaxAgeMs)
        Provider entries in the global capabilities directory are cached locally. Discovery will consider entries in this cache valid if they are younger than the max age of cached providers as defined in the QoS. All valid entries will be processed by the arbitrator when searching for and arbitrating the "best" matching provider.

        NOTE: Valid cache entries might prevent triggering a lookup in the global capabilities directory. Therefore, providers registered with the global capabilities after the last lookup and before the cacheMaxAge expires will not be discovered.

        Parameters:
        cacheMaxAgeMs - Maximum age of entries in the localCapabilitiesDirectory. If this value filters out all entries of the local capabilities directory a lookup in the global capabilitiesDirectory will take place.

      • isLocalOnly

        public boolean isLocalOnly()

      • getRetryIntervalMs

        public long getRetryIntervalMs()
        Returns:
        the interval used for retrying discovery if the previous attempt was unsuccessful

      • setRetryIntervalMs

        public void setRetryIntervalMs​(long retryIntervalMs)
        Parameters:
        retryIntervalMs - The time to wait between discovery retries after unsuccessful discovery attempts. The actual delay may be longer, as there is a system-wide minimum delay (see ConfigurableMessagingSettings.PROPERTY_DISCOVERY_MINIMUM_RETRY_INTERVAL_MS).

      • getProviderMustSupportOnChange

        public boolean getProviderMustSupportOnChange()
        Indicates if arbitration should only consider providers that support onChange subscriptions
        Returns:
        true if only providers that support onChange subscriptions are considered

      • setProviderMustSupportOnChange

        public void setProviderMustSupportOnChange​(boolean providerMustSupportOnChange)
        Indicates if arbitration should only consider providers that support onChange subscriptions
        Parameters:
        providerMustSupportOnChange - true if only providers that support onChange subscriptions should be considered

      • setDiscoveryScope

        public void setDiscoveryScope​(DiscoveryScope discoveryScope)
        Parameters:
        discoveryScope - selects capability registries to choose from for provider discovery

      • getDiscoveryScope

        public DiscoveryScope getDiscoveryScope()
        Returns:
        scope criteria to select from capability registries for provider discovery

      • toString

        public String toString()
        Stringifies the class excluding arbitrationStrategyFunction
        Overrides:
        toString in class Object
        Returns:
        stringified class content excluding arbitrationStrategyFunction