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 Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CQS_INTERNAL_ID`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `checkPermission(LiveViewPermission permission)` Checks whether the authenticated user has the specified permission.
    `List<Boolean>` | `checkPermissions(List<LiveViewPermission> permissions)` Checks whether the authenticated user has the specified permissions.
    `void` | `close()` Closes all queries and open resources with the server.
    `void` | `deleteRows(QueryConfig config)` Delete rows based on the supplied `QueryConfig`.
    `Query` | `describeQuery(QueryConfig config)` Get information about a query, such as its result schema, without actually running it
    `SnapshotResult` | `executeSnapshotQuery(QueryConfig config)` 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.
    `AlertManager` | `getAlertManager()`
    `<T extends LiveViewServerCapability> T` | `getCapability(Class<T> typeOfCapability)` 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.
    `ClientController` | `getClientController()` A ClientController is used to perform actions to control clients.
    `String` | `getConnectionURI()` Retrieves the URI that was used to connect to the server
    `SendTupleInfo` | `getSendTupleInfo(StreamBaseURI sbUri, String targetInputStreamName, String responseOutputStreamName)` Gets the schemas associated with streams, for the purposes of using SendTupleAction.
    `ServerUtilityDataProvider` | `getServerUtilityDataProvider()`
    `Table` | `getTable(String name)` Retrieve a specific table from the server
    `TableAdminManager` | `getTableAdminManager()` Get the TableAdminManager, which provides an API to administer tables in the server.
    `<T extends LiveViewServerCapability> boolean` | `hasCapability(Class<T> typeOfCapability)` Returns true if the connected server supports the given type of capability.
    `boolean` | `isConnected()` A polling method to check if the connection with the server is still valid.
    `List<Table>` | `listTables()` Lists the available tables for querying
    `List<Table>` | `listTables(boolean includeSystemTables)` List the available tables for querying
    `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`.
    `void` | `registerTableListListener(TableListListener listener, boolean includeSnapshot)` If you want to be informed of changes to the Table List, then register a Listener with this method.
    `Tuple` | `sendTupleAction(StreamBaseURI sbUri, String targetInputStreamName, Tuple tuple, String responseOutputStreamName, Schema expectedResponseSchema, long timeout, TimeUnit unit)` Sends a tuple to an existing StreamBase application.

- - ### Field Detail

    - #### CQS_INTERNAL_ID

          static final String CQS_INTERNAL_ID

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### 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.
      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:
      - `QueryConfig.setMaxResultSetSize(int)`
      - `QueryConfig.setPredicate(java.lang.String)`
      - `QueryConfig.setQuery(java.lang.String, java.lang.String)`
      - `QueryConfig.setTable(java.lang.String)`
      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

Copyright © 2015–2018 Cloud Software Group, Inc.. All rights reserved.