Package com.illumon.iris.controller

Interface IServerSelectionProvider

All Known Implementing Classes:
SimpleServerSelectionProvider
public interface IServerSelectionProvider
Interface for persistent query and console server selection implementations. These provide customer-implemented server-selection algorithms.

Implementations must have a constructor that takes:

  • log - a Logger that can be used for logging
  • serverGroupProvider - a IrisGroupProvider that can be used to determine allowed servers

  • Method Details

    • getServerGroups

      @NotNull Set<IServerSelectionProvider.ServerGroup> getServerGroups()
      List the available server groups. Each server group will be added to ths list of servers available for query server selection.
      Returns:
      the set of available server groups

    • determineServer

      @NotNull PersistentQueryDbServerConfig determineServer(@NotNull String serverGroupName, @NotNull UserContext UserContext, int heapSizeMB, @NotNull String workerKind, String description, @Nullable PersistentQueryConfiguration configuration) throws IServerSelectionProvider.ResourcesUnavailableException
      Determine the server (dispatcher) on which to request the worker.
      Parameters:
      serverGroupName - the user-chosen host or server group
      UserContext - the user context when available (internally-generated starts may not have a user context)
      heapSizeMB - the requested heap size in MB
      workerKind - the kind of worker that will be created
      description - a text description of the requested worker
      configuration - the configuration for a persistent query, or null for consoles or other non-PQ workers
      Returns:
      a PersistentQueryDbServerConfig that represents the server (dispatcher) on which to request the worker
      Throws:
      IServerSelectionProvider.ResourcesUnavailableException - if a server can't be determined

    • updateServerTotalHeapMB

      void updateServerTotalHeapMB(@NotNull PersistentQueryDbServerConfig serverConfig, int totalHeapMB)
      Update the total heap available for a server. This will be determined by the controller after getting a connection to each dispatcher.
      Parameters:
      serverConfig - the server configuration
      totalHeapMB - the total available heap for the dispatcher

    • setServerUsage

      void setServerUsage(@NotNull PersistentQueryDbServerConfig serverConfig, int usageMB, int availableMB, int workerCount)
      Set the current server usage. This may be on an initial dispatcher connection or after a reconnection, or whenever the utilization changes.
      Parameters:
      serverConfig - the server configuration
      usageMB - the usage in MB
      availableMB - the server's availability as reported by the dispatcher
      workerCount - the current number of workers running on that server

    • addWorkerForSerial

      void addWorkerForSerial(@NotNull PersistentQueryDbServerConfig serverConfig, long serial, String workerProcessInfoId)
      Add a worker for the given persistent query serial number.

      The server selection provider may use the worker count per PQ to more evenly distribute replicas across the cluster so that the failure of one query node is less likely to make all replicas of a query unavailable.

      Parameters:
      serverConfig - the server configuration
      serial - the serial number of the persistent query that is starting a new worker
      workerProcessInfoId - the process info ID of the worker

    • removeWorkerForSerial

      void removeWorkerForSerial(@NotNull PersistentQueryDbServerConfig serverConfig, long serial, String workerProcessInfoId)
      Remove a worker for the given persistent query serial number.

      The server selection provider may use the worker count per PQ to more evenly distribute replicas across the cluster so that the failure of one query node is less likely to make all replicas of a query unavailable.

      Parameters:
      serverConfig - the server configuration
      serial - the serial number of the persistent query that has removed a worker
      workerProcessInfoId - the process info ID of the worker

    • updateWorkerStatus

      void updateWorkerStatus(PersistentQueryDbServerConfig serverConfig, long serial, @NotNull String workerProcessInfoId, @NotNull PersistentQueryState.Status status)
      Set the status of a worker for the given persistent query serial number.

      The server selection provider may use this information to `guess` about server health.

      Parameters:
      serverConfig - the server configuration
      serial - the serial number of the persistent query that has removed a worker
      workerProcessInfoId - the process info ID of the worker
      status - the most recent status transition for the worker

    • updateServerAvailability

      void updateServerAvailability(@NotNull PersistentQueryDbServerConfig serverConfig, boolean available)
      Update whether a server is available or not.
      Parameters:
      serverConfig - the server configuration
      available - if true, the server is available; if false, it is not

    • updateServerMaxHeapGB

      void updateServerMaxHeapGB(PersistentQueryDbServerConfig serverConfig, double maxHeapSizeGB)
      Update the max per-worker heap size in GB for a server based on the dispatcher's actual configuration.
      Parameters:
      serverConfig - the server configuration
      maxHeapSizeGB - the new maximum size

    • updateServerInfo

      void updateServerInfo(PersistentQueryDbServerConfig serverConfig, String json)
      Update the server info JSON for a server based on the dispatcher's actual configuration.
      Parameters:
      serverConfig - the server configuration
      json - the server's JSON server info configuration

    • generateReloadableConfigurationElement

      void generateReloadableConfigurationElement(org.jdom2.Element baseElement, com.fishlib.configuration.Configuration config)
      Generate an Element with this server selection provider's configuration. This element will be used to load the configuration indirectly. This element may be generated in a different process than the controller.
      Parameters:
      baseElement - the Element
      config - the Configuration to be used to generate the Element

    • verifyConfiguration

      void verifyConfiguration(@NotNull org.jdom2.Element element, List<PersistentQueryDbServerConfig> serverConfigs) throws ConfigurationVerificationException
      Given the Element generated by generateReloadableConfigurationElement(org.jdom2.Element, com.fishlib.configuration.Configuration), validate and prepare the configuration for use.
      Parameters:
      element - the generated Element containing the configuration
      serverConfigs - the available dispatchers as determined by the controller
      Throws:
      ConfigurationVerificationException - if the provided element can't be used for any reason

    • installConfiguration

      void installConfiguration()
      Install the verified configuration. This will be called after verifyConfiguration(org.jdom2.Element, java.util.List<com.illumon.iris.controller.PersistentQueryDbServerConfig>) is successfully called and indicates that the verified configuration should now be used.

    • generateStateInformation

      String generateStateInformation(@NotNull UserContext userContext)
      Return information about the selection provider, which can be used for debugging or monitoring.

      The state format is defined by the selection provider, but the suggested format is JSON for simple parsing with jq or other tools.

      Parameters:
      userContext - the user requesting the state
      Returns:
      a string representation of the internal state of this selection provider.

    • adminCommand

      String adminCommand(@NotNull UserContext userContext, @NotNull String command)
      Issue an administrative command to the selection provider.
      Parameters:
      userContext - the user requesting the command
      command - the administrative command
      Returns:
      a string representation of the result