Package com.streambase.liveview.client

Interface LiveViewConnection

All Superinterfaces:
AutoCloseable, Closeable
All Known Subinterfaces:
LiveViewMultiConnection
public interface LiveViewConnection extends Closeable
A client connection to a LiveView server. Using the connection a client can list the tables on the server and register queries. Methods of the LiveViewConnection are not guaranteed to be thread safe. Unexpected results may occur if multiple threads call methods concurrently on a LiveViewConnection.

  • Field Details

  • Method Details

    • listTables

      List<Table> listTables() throws LiveViewException
      Lists the available tables for querying
      Returns:
      List of tables available for querying
      Throws:
      LiveViewException - if table list cannot be retrieved

    • listTables

      List<Table> listTables(boolean includeSystemTables) throws LiveViewException
      List the available tables for querying
      Parameters:
      includeSystemTables - - if true, system tables are included in the list
      Returns:
      List of tables available for querying
      Throws:
      LiveViewException - if table list cannot be retrieved

    • registerTableListListener

      void registerTableListListener(TableListListener listener, boolean includeSnapshot) throws LiveViewException
      If you want to be informed of changes to the Table List, then register a Listener with this method. It will be called asynchronously, so beware of thread safety issues as you use this info. Call this with null if you no longer want to listen.
      Parameters:
      listener -
      includeSnapshot - if true, your listener will get current snapshot data (plus changes); if false, only changes.
      Throws:
      LiveViewException

    • getTable

      Table getTable(String name) throws LiveViewException
      Retrieve a specific table from the server
      Parameters:
      name - name of the table to retrieve
      Returns:
      An instance of the server table
      Throws:
      LiveViewException - if the table does not exists or another server side error occurs.

    • close

      void close()
      Closes all queries and open resources with the server. A connection cannot be reused after closing.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • isConnected

      boolean isConnected()
      A polling method to check if the connection with the server is still valid. This method may block for network activity if the server is unresponsive.
      Returns:
      true is the connection with the server is valid, false otherwise.

    • hasCapability

      <T extends LiveViewServerCapability> boolean hasCapability(Class<T> typeOfCapability)
      Returns true if the connected server supports the given type of capability.
      Parameters:
      typeOfCapability - Class that represents a capability
      Returns:
      True if the connected server supports the given type of capability, false if it doesn't or the connection is not active

    • getCapability

      <T extends LiveViewServerCapability> T getCapability(Class<T> typeOfCapability) throws NoSuchCapabilityException, LiveViewException
      Returns the object that represents a capability of the connected server, or throws NoSuchCapabilityException if the type of capability is not supported by the server.
      Parameters:
      typeOfCapability - Class that represents a capability
      Returns:
      The object that represents a capability of the connected server
      Throws:
      NoSuchCapabilityException - if the type of capability is not supported by the server
      LiveViewException - if the LiveViewConnection is not currently connected.

    • registerQuery

      Query registerQuery(QueryConfig config, QueryListener listener)
      Registers a new query on the server based on the QueryConfig and sends query events to the specified QueryListener. Depending on the query configuration the server will return snapshot only data or snapshot followed by continuous updates.

      NOTE: The QueryListener callbacks should return quickly. In some situations, long running callbacks can trigger heartbeat failures and/or other connection problems, particularly in the face of high data rates.

      Parameters:
      config - the configuration of the query
      listener - specifies the listener that will receive the query events
      Returns:
      a query object that the client can use to manage the query lifecycle. null will be return if server does not support new delete api (server version older than 1.5.2).

    • describeQuery

      Query describeQuery(QueryConfig config) throws LiveViewException
      Get information about a query, such as its result schema, without actually running it
      Parameters:
      config - the configuration of query
      Returns:
      a Query with information about the given configuration. The query is already closed; callers do not need to call Query.close() on the return value.
      Throws:
      LiveViewException - if there is a problem with the query configuration or another server exception occurs

    • deleteRows

      void deleteRows(QueryConfig config) throws LiveViewException
      Delete rows based on the supplied QueryConfig. The issuer of this delete does not know how many rows were removed, or when the delete completes. Only a subset of the QueryConfig options are valid for deleteRows, you may set: deleteRows is effectively a snapshot query where the results of the query is the data to be deleted.
      Parameters:
      config - the configuration of the query
      Throws:
      LiveViewException - if there is a problem with the query configuration or another server exception occurs
      Since:
      1.4

    • executeSnapshotQuery

      SnapshotResult executeSnapshotQuery(QueryConfig config) throws LiveViewException
      This method makes it easy to run a snapshot-only query where the results come back in an object that can be iterated over to retrieve the snapshot tuples. Note that the LiveViewQueryType setting in QueryConfig will be ignored because this method is always LiveViewQueryType.SNAPSHOT This method returns as soon as the query is successfully regiestered, but before the data has arrived. However, the SnapshotResult that is returned will block appropriately in its next and hasNext methods, so you can immediately start using it as if it were an iterator.
      Parameters:
      config - the configuration of the query
      Returns:
      Iterator pattern for retrieving the snapshot tuples
      Throws:
      LiveViewException - if there is a problem with the query configuration or another server exception occurs
      Since:
      1.2

    • getConnectionURI

      String getConnectionURI()
      Retrieves the URI that was used to connect to the server
      Returns:
      URI used to make the server connection

    • getTableAdminManager

      TableAdminManager getTableAdminManager() throws LiveViewException
      Get the TableAdminManager, which provides an API to administer tables in the server.
      Returns:
      a TableAdminManager.
      Throws:
      LiveViewException
      Since:
      2.1

    • getClientController

      ClientController getClientController() throws LiveViewException
      A ClientController is used to perform actions to control clients. See ClientController
      Returns:
      Returns a client controller
      Throws:
      LiveViewException
      Since:
      2.1

    • getAlertManager

      AlertManager getAlertManager() throws LiveViewException
      Returns:
      An AlertManager, which provides an API to manage alerts on this server.
      Throws:
      LiveViewException
      Since:
      2.0

    • getServerUtilityDataProvider

      ServerUtilityDataProvider getServerUtilityDataProvider() throws LiveViewException
      Returns:
      A ServerUtilityDataProvider, which provides API to get utility data from the server.
      Throws:
      LiveViewException
      Since:
      2.1

    • getSendTupleInfo

      SendTupleInfo getSendTupleInfo(StreamBaseURI sbUri, String targetInputStreamName, String responseOutputStreamName) throws LiveViewException
      Gets the schemas associated with streams, for the purposes of using SendTupleAction.
      Parameters:
      sbUri - (Optional) URI of the StreamBase server. The LV server's current SB server will be used if null.
      targetInputStreamName - The pathname of the input stream to which to send the tuple
      responseOutputStreamName - (Optional) pathname of OutputStream to listen for a response
      Returns:
      information about the streams, as defined on the server.
      Throws:
      LiveViewException
      Since:
      2.0.1

    • sendTupleAction

      Tuple sendTupleAction(StreamBaseURI sbUri, String targetInputStreamName, Tuple tuple, String responseOutputStreamName, Schema expectedResponseSchema, long timeout, TimeUnit unit) throws LiveViewException
      Sends a tuple to an existing StreamBase application. If responseOutputStreamName and expectedResponseSchema are BOTH non-null, it will wait for a corresponding tuple to be output from the outputStream. Note that the app must be written such that the BOTH the inputStream and the OutputStream must have a String field named "__SendTupleResponseKey" or it will give an error. This field will be set by the server when sending the tuple, and the response will be checked that it has the same value. (This is to prevent one client from getting a response that was intended for a different client). If the client has not included the responseOutputStreamName, then the field is not required.
      Parameters:
      sbUri - (Optional) URI of the StreamBase server. The LV server's current SB server will be used if null.
      targetInputStreamName - The pathname of the input stream to which to send the tuple
      tuple - The tuple to send
      responseOutputStreamName - (Optional) pathname of OutputStream to listen for a response
      expectedResponseSchema - (Optional) The schema that the response is expected to have, likely retrieved via getSendTupleInfo
      timeout - Maximum time to wait for response. Valid range is 50 - 120000 MILLISECONDS
      unit - (Optional) units for the timeout. If null, TimeUnit.MILLISECONDS will be assumed.
      Returns:
      null unless outputStreamName and synchFieldName are both non-null, otherwise the response Tuple
      Throws:
      LiveViewException
      Since:
      2.0.1

    • checkPermissions

      List<Boolean> checkPermissions(List<LiveViewPermission> permissions) throws LiveViewException
      Checks whether the authenticated user has the specified permissions. This method always returns true when authentication is disabled.
      Parameters:
      permissions - a list of permissions to check for
      Returns:
      a list of booleans corresponding to the permissions being checked for, with true indicating the user has the permission
      Throws:
      LiveViewException
      Since:
      2.0.1

    • checkPermission

      boolean checkPermission(LiveViewPermission permission) throws LiveViewException
      Checks whether the authenticated user has the specified permission. This method always returns true when authentication is disabled.
      Parameters:
      permission - a single permission to check for
      Returns:
      a boolean with true indicating the user has the permission being checked for and false otherwise
      Throws:
      LiveViewException
      Since:
      2.0.1