Package io.deephaven.enterprise.controller.client

Class ControllerClientGrpc

java.lang.Object
io.deephaven.enterprise.controller.client.ControllerClientGrpc
public class ControllerClientGrpc extends Object

A client for subscribing to state from the PersistentQueryController and manipulating persistent queries.

In order to connect to the Persistent Query Controller you must first add an ControllerClientGrpc.Observer then authenticate(AuthToken). You can use the authentication client to create an AuthToken for this. Once authenticated, a call to subscribe() or subscribeToAll() will request a complete snapshot of queries that the authenticated user is allowed to see. Until you call shutdown() the Persistent Query Controller will deliver updates to the queries to the ControllerClientGrpc.Observers, and you may use the query manipulation methods to manage queries.

Warning:

Before authentication and subscription you must add an ControllerClientGrpc.Observer to handle asynchronous events, like a successful connection or update delivery. If you instead call authenticate(AuthToken) and subscribe() before adding an observer, you will miss delivery of the initial snapshot of query configuration and state.

  • Field Details

  • Constructor Details

    • ControllerClientGrpc

      public ControllerClientGrpc(@NotNull String who, @NotNull io.deephaven.shadow.core.io.grpc.ManagedChannel channel, @NotNull ScheduledExecutorService executorService, @NotNull AuthenticationClient authenticationClient, long heartBeatPeriodMillis, long heartBeatTimeoutMillis)

    • ControllerClientGrpc

      public ControllerClientGrpc(@NotNull String who, @NotNull io.deephaven.shadow.core.io.grpc.ManagedChannel channel, @NotNull ScheduledExecutorService executorService, @NotNull TokenFactoryFactory.TokenFactory tokenFactory, long heartBeatPeriodMillis, long heartBeatTimeoutMillis)

  • Method Details

    • withRetriesAndReAuth

      protected <ReqT, RespT, Stub> RespT withRetriesAndReAuth(String who, Function<io.deephaven.shadow.core.com.google.protobuf.ByteString,ReqT> authCookieToRequestFun, LongFunction<Stub> stubFun, Function<Stub,BiConsumer<ReqT,io.deephaven.shadow.core.io.grpc.stub.StreamObserver<RespT>>> callFun, long timeToDeadlineMillis)

    • withRetriesAndReAuth

      protected <ReqT, RespT, Stub, V> V withRetriesAndReAuth(String who, Function<io.deephaven.shadow.core.com.google.protobuf.ByteString,ReqT> authCookieToRequestFun, LongFunction<Stub> stubFun, Function<Stub,BiConsumer<ReqT,io.deephaven.shadow.core.io.grpc.stub.StreamObserver<RespT>>> callFun, Function<RespT,V> responseMapping, long timeToDeadlineMillis)
      Perform an RPC call with retries if necessary, including both call retries and necessary authentication retries depending on type of failure. The implementation assumes the existence of a service configuration file at channel creation that enables retries on all stubs that this method will be used with; the retry strategy for the non-reauthentication retries (meaning the stub call itself) will be done according to the strategy defined in that service config. Authentication retries are done when the stub call fails with Status.UNAUTHENTICATED, and follow the strategy defined by authRetryStrategy
      Type Parameters:
      ReqT - The type of the request for the RPC call
      RespT - The type of the response for the RPC call
      Stub - The type for the stub where the RPC call is made
      V - The return value of the responseMapping and this method
      Parameters:
      who - A string identifier for the caller used for logging
      authCookieToRequestFun - A function taking an auth cookie and expected to return the request object to provide as an argument to the RPC call to make
      stubFun - A function taking a time in milliseconds to deadline and expected to return a stub configured with that deadline and any other necessary configuration options for the desired retry strategy (eg, wait for ready)
      callFun - A function taking a stub (the one produced via authCookieToRequestFun and expected to return the RPC call to make
      responseMapping - A function taking the RPC call's response and expected to return a value to be returned by this function. Pass the identity function to get the actual RPC return type and value.
      timeToDeadlineMillis - A time in milliseconds from now to a deadline when to stop retrying
      Returns:
      The result of the RPC call mapped using responseMapping

    • authenticate

      public boolean authenticate(@NotNull AuthToken token)
      Use the specified auth token to authenticate this client to the hashtable server.
      Parameters:
      token - the token for authentication
      Returns:
      true if authentication was successful.

    • authenticateAsync

      @NotNull public CompletableFuture<io.deephaven.shadow.core.com.google.protobuf.ByteString> authenticateAsync(@NotNull AuthToken token)
      Use the specified auth token to authenticate this client to the hashtable server.
      Parameters:
      token - the token for authentication
      Returns:
      a CompletableFuture that can be used to asynchronously wait for authentication to complete.

    • authenticateAsync

      protected CompletableFuture<io.deephaven.shadow.core.com.google.protobuf.ByteString> authenticateAsync(long maxTimeToDeadlineMillis, @NotNull AuthToken token)

    • setEphemeral

      public void setEphemeral()
      Set the channel as ephemeral. In this mode when a heartbeat is missed, the client halts further heartbeats, ends any active grpc stream, and generates no further connection events.

    • isTerminal

      public boolean isTerminal(@NotNull PersistentQueryStatusEnum status)

    • isRunning

      public boolean isRunning(@NotNull PersistentQueryStatusEnum status)

    • addObserver

      public void addObserver(@NotNull ControllerClientGrpc.Observer observer)
      Add a status listener. If the service is already available, the listener will be invoked immediately on the thread pool.
      Parameters:
      observer - the listener to add

    • removeObserver

      public void removeObserver(ControllerClientGrpc.Observer observer)

    • isConnected

      public boolean isConnected()
      Check if this client can communicate with the server.
      Returns:
      true if it can

    • subscribeToAll

      public void subscribeToAll()
      Subscribe to the complete hash table.

    • shutdown

      public void shutdown() throws IOException
      Throws:
      IOException

    • getConfiguration

      public ControllerConfigurationMessage getConfiguration()
      Gets the server configuration from the controller.
      Returns:
      the currently loaded controller configuration

    • reloadConfiguration

      public void reloadConfiguration()
      Command the PersistentQueryController to reload parts of its configuration without requiring a controller restart. The controller will broadcast the updated configuration to all connected clients.
      ApiNote:
      Not all properties or configuration parameters may be reloaded.

    • serverSelectionStatus

      public String serverSelectionStatus()
      Gets the server selection provider status.
      Returns:
      the free-form status information

    • serverSelectionAdmin

      public String serverSelectionAdmin(String command)
      Execute a server selection provider admin command.
      Returns:
      the free-form result

    • addQueryConfiguration

      public long addQueryConfiguration(@NotNull PersistentQueryConfigMessage config)
      Adds a configuration to the controller's hash table.
      Parameters:
      config - the configuration to add
      Returns:
      the serial number of the added configuration

    • determineDispatcher

      public PQDBServerConfigMessage determineDispatcher(@NotNull PQDBServerConfigMessage serverConfig, int heapSizeMB, String workerKind)

    • determineDispatcher

      public PQDBServerConfigMessage determineDispatcher(@NotNull String serverConfigName, int heapSizeMB, String workerKind)

    • modifyQueryConfiguration

      public void modifyQueryConfiguration(@NotNull PersistentQueryConfigMessage config)
      Modifies a configuration in the controller's hash table, and restart the query if it was running.
      Parameters:
      config - the updated configuration

    • modifyQueryConfiguration

      public void modifyQueryConfiguration(@NotNull PersistentQueryConfigMessage config, boolean restartIfRunning)
      Modifies a configuration in the controller's hash table.
      Parameters:
      config - the updated configuration
      restartIfRunning - restart the query when it is running if set to true

    • removeQueryConfiguration

      public void removeQueryConfiguration(PersistentQueryConfigMessage config)
      Removes a configuration from the controller's hash table.
      Parameters:
      config - the configuration to remove

    • removeQueryConfigurationBySerial

      public void removeQueryConfigurationBySerial(long serialId)
      Removes a configuration from the controller's hash table by serial ID.
      Parameters:
      serialId - the serial ID of configuration to remove

    • restartQuery

      public void restartQuery(PersistentQueryConfigMessage config)
      Restart a persistent query. This implementation delegates to restartQueries(List) )}.
      Parameters:
      config - the persistent query configuration to be restarted.

    • restartQueries

      public void restartQueries(@NotNull List<PersistentQueryConfigMessage> configs)
      Restarts one or more persistent queries.
      Parameters:
      configs - the persistent query configurations to be restarted

    • restartReplicas

      public void restartReplicas(@NotNull List<ReplicaSpecifier> replicas)

    • restartQueriesBySerial

      public void restartQueriesBySerial(@NotNull long[] serialIds)
      Restarts one or more persistent queries.
      Parameters:
      serialIds - an array of serial ids to restart

    • restartQueriesBySerial

      public void restartQueriesBySerial(@NotNull List<Long> serials)
      Restarts one or more persistent queries.
      Parameters:
      serials - a list of serial ids to restart

    • stopQuery

      public void stopQuery(PersistentQueryConfigMessage config)
      Stops a persistent query.
      Parameters:
      config - the persistent query configuration to be stopped.

    • stopQueries

      public void stopQueries(@NotNull List<PersistentQueryConfigMessage> configs)
      Stops one or more persistent queries.
      Parameters:
      configs - the persistent query configurations to be stopped

    • stopQueryBySerial

      public void stopQueryBySerial(@NotNull long[] serials)
      Stops one or more persistent query by serial id.
      Parameters:
      serials - the serial ids of the persistent query configurations to be stopped

    • stopQueryBySerial

      public void stopQueryBySerial(@NotNull List<Long> serials)
      Stop a set of queries by their serials.
      Parameters:
      serials - the serials to stop

    • publishStatusUpdate

      public void publishStatusUpdate(long querySerial, String processInfoId, @Nullable PersistentQueryStatusEnum status, @Nullable Map<String,ExportedObjectInfoMessage> scopeFields, @Nullable Map<String,String[]> tableGroups)
      Publish a status update for the specified query.
      Parameters:
      querySerial - The query serial to update.
      status - An optional status update, null if not present
      scopeFields - an optional set of field updates, null if not present
      tableGroups - an optional set of table groups, null if not present

    • getScriptPathsByOwner

      @NotNull public Set<String> getScriptPathsByOwner(@NotNull String owner, @Nullable String loaderStateJson)
      Fetch all available script display paths based on the specified user.
      Parameters:
      owner - the user
      loaderStateJson - optional extra script loader state information in JSON format
      Returns:
      the set of available script paths.

    • getScriptPathsBySerial

      @NotNull public Set<String> getScriptPathsBySerial(long querySerial, @Nullable String loaderStateJson)
      Fetch all available script display paths based on the configuration of a query.
      Parameters:
      querySerial - the query serial
      loaderStateJson - optional extra script loader state information in JSON format
      Returns:
      the set of available script paths.

    • getAllScriptPaths

      @NotNull public Set<String> getAllScriptPaths(@Nullable String loaderStateJson)
      Fetch all available script display paths based on the currently authenticated user.
      Parameters:
      loaderStateJson - optional extra script loader state information in JSON format
      Returns:
      the set of available script paths.

    • getScriptPathsByOwner

      @NotNull public Set<String> getScriptPathsByOwner(@NotNull String owner, @Nullable String loaderStateJson, boolean useRelativePath)
      Fetch all available script relative or display paths based on the specified user.
      Parameters:
      owner - the user
      loaderStateJson - optional extra script loader state information in JSON format
      useRelativePath - whether to return relative or display script paths
      Returns:
      the set of available script paths.

    • getScriptPathsBySerial

      @NotNull public Set<String> getScriptPathsBySerial(long querySerial, @Nullable String loaderStateJson, boolean useRelativePath)
      Fetch all available script relative or display paths based on the configuration of a query.
      Parameters:
      querySerial - the query serial
      loaderStateJson - optional extra script loader state information in JSON format
      useRelativePath - whether to return relative or display script paths
      Returns:
      the set of available script paths.

    • getAllScriptPaths

      @NotNull public Set<String> getAllScriptPaths(@Nullable String loaderStateJson, boolean useRelativePath)
      Fetch all available script relative or display paths based on the currently authenticated user.
      Parameters:
      loaderStateJson - optional extra script loader state information in JSON format
      useRelativePath - whether to return relative or display script paths
      Returns:
      the set of available script paths.

    • getScriptBody

      @Nullable public String getScriptBody(@NotNull String scriptPath, @Nullable String loaderStateJson, boolean isPathRelative)
      Fetch the body of the specified script as the currently authenticated user.
      Parameters:
      scriptPath - the path to the script
      loaderStateJson - optional extra script loader state information in JSON format
      isPathRelative - true if the path should be treated as a relative path
      Returns:
      the text of the script body, or null if it could not be fetched

    • getScriptBodyBySerial

      @Nullable public String getScriptBodyBySerial(long querySerial, @NotNull String scriptPath, @Nullable String loaderStateJson, boolean isPathRelative)
      Fetch the body of the specified script using the details of the specified query.
      Parameters:
      querySerial - the serial of the query
      scriptPath - the path to the script
      loaderStateJson - optional extra script loader state information in JSON format
      isPathRelative - true if the path should be treated as a relative path
      Returns:
      the text of the script body, or null if it could not be fetched

    • getScriptBodyByOwner

      @Nullable public String getScriptBodyByOwner(@NotNull String owner, @NotNull String scriptPath, @Nullable String loaderStateJson, boolean isPathRelative)
      Fetch the body of the specified script as the specified user.
      Parameters:
      owner - the user to fetch the script as
      scriptPath - the path to the script
      loaderStateJson - optional extra script loader state information in JSON format
      isPathRelative - true if the path should be treated as a relative path
      Returns:
      the text of the script body, or null if it could not be fetched

    • getGroupsForUser

      public String[] getGroupsForUser(UserContext userContext)
      Return the groups which a user belongs to.
      Parameters:
      userContext - the UserContext to get membership for
      Returns:
      an array of group names that the effective user belongs to

    • getUsersForGroup

      public String[] getUsersForGroup(String group)
      Return the users which belong to a group.
      Parameters:
      group - the group to get membership for
      Returns:
      an array of usernames that belong to the group

    • isSuperUser

      public boolean isSuperUser(@NotNull UserContext userContext)
      Returns true if the effective user is a superuser.
      Parameters:
      userContext - the UserContext to query
      Returns:
      true if the user is a member of the iris-superusers group.

    • isAclEditor

      public boolean isAclEditor(@NotNull UserContext userContext)
      Returns true if the effective user is an ACL editor
      Parameters:
      userContext - the UserContext to query
      Returns:
      true if the user is a member of the iris-acleditors group.

    • isSchemaManager

      public boolean isSchemaManager(@NotNull UserContext userContext)
      Returns true if the effective user is a Schema manager
      Parameters:
      userContext - the UserContext to query
      Returns:
      true if the user is a member of the iris-schemamanagers group.

    • isQueryManager

      public boolean isQueryManager(@NotNull UserContext userContext)
      Returns true if the effective user is an Query Manager
      Parameters:
      userContext - the UserContext to query
      Returns:
      true if the user is a member of the iris-querymanagers group.

    • getAllGroups

      public String[] getAllGroups()
      Returns the list of all groups.
      Returns:
      an array of all group names

    • getAllUsers

      public String[] getAllUsers()
      Returns the list of all users.
      Returns:
      an array of all user names

    • handleConnectionLost

      protected void handleConnectionLost()

    • handleConnectionReestablished

      protected void handleConnectionReestablished()

    • makeNamedStringList

      public static NamedStringList makeNamedStringList(@NotNull String name, @Nullable String[] list)
      Create a NamedStringList object from a string array and name.
      Parameters:
      name - the name to use
      list - the array of values
      Returns:
      a new NamedStringList

    • makeNamedStringList

      @NotNull public static NamedStringList makeNamedStringList(@NotNull String name, @Nullable Collection<String> list)
      Create a NamedStringList object from a collection of strings and name.
      Parameters:
      name - the name to use
      list - the collection of values
      Returns:
      a new NamedStringList

    • simulateConnectionLost

      @TestUseOnly public void simulateConnectionLost()
      Simulate a connection lost for testing