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.

    • Method Detail

      • 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

      • 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

      • 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