com.streambase.liveview.client

Interface LiveViewConnection

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

All Known Subinterfaces:

LiveViewMultiConnection

public interface LiveViewConnection
extends java.io.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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	LiveViewConnection.TableProviderAPIHelper Deprecated. Use TableAdminManager.TableProviderAPIHelper, instead

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CQS_INTERNAL_ID

Method Summary

Modifier and Type	Method and Description
void	addTableProvider(java.lang.String id, com.streambase.liveview.internal.protocol.jaxb.ExternalConnectionTypeType externalConnectionType, java.lang.String javaClassName, com.streambase.liveview.internal.protocol.jaxb.ExternalServerConnectionType.Parameters parameters, com.streambase.liveview.internal.protocol.jaxb.ExternalServerConnectionType.Mappings mappings, int maxFailAttempts, int waitSeconds) Deprecated. Use TableAdminManager, instead Connect to a TableProvider, which then allows for remote connections as if they were LiveView Tables.
boolean	checkPermission(LiveViewPermission permission) Checks whether the authenticated user has the specified permission.
java.util.List<java.lang.Boolean>	checkPermissions(java.util.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(java.lang.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.
java.lang.String	getConnectionURI() Retrieves the URI that was used to connect to the server
SendTupleInfo	getSendTupleInfo(StreamBaseURI sbUri, java.lang.String targetInputStreamName, java.lang.String responseOutputStreamName) Gets the schemas associated with streams, for the purposes of using SendTupleAction.
ServerUtilityDataProvider	getServerUtilityDataProvider()
Table	getTable(java.lang.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(java.lang.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.
java.util.List<Table>	listTables() Lists the available tables for querying
java.util.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.
void	removeTableProvider(java.lang.String id) Deprecated. Use TableAdminManager, instead
Tuple	sendTupleAction(StreamBaseURI sbUri, java.lang.String targetInputStreamName, Tuple tuple, java.lang.String responseOutputStreamName, Schema expectedResponseSchema, long timeout, java.util.concurrent.TimeUnit unit) Sends a tuple to an existing StreamBase application.

Field Detail

CQS_INTERNAL_ID

static final java.lang.String CQS_INTERNAL_ID

See Also:

Constant Field Values

Method Detail

listTables

java.util.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

java.util.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(java.lang.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 java.lang.AutoCloseable

Specified by:

close in interface java.io.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(java.lang.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(java.lang.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:

• 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

java.lang.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

addTableProvider

void addTableProvider(java.lang.String id,
                      com.streambase.liveview.internal.protocol.jaxb.ExternalConnectionTypeType externalConnectionType,
                      java.lang.String javaClassName,
                      com.streambase.liveview.internal.protocol.jaxb.ExternalServerConnectionType.Parameters parameters,
                      com.streambase.liveview.internal.protocol.jaxb.ExternalServerConnectionType.Mappings mappings,
                      int maxFailAttempts,
                      int waitSeconds)
               throws LiveViewException

Deprecated. Use TableAdminManager, instead Connect to a TableProvider, which then allows for remote connections as if they were LiveView Tables.

Parameters:

id - must be unique on the LiveView server.

externalConnectionType - one of CEP_QUERY_TABLES, LIVE_VIEW, CUSTOM_TABLE_PROVIDER ExternalConnectionTypeType

javaClassName - The className of a class which implements com.streambase.liveview.server.table.TableProvider. Only used if type is CUSTOM_TABLE_PROVIDER.

parameters - key-value pairs that are specific to your TableGenerator. Use utility function TableProviderAPIHelper#addMapping(Mappings, String, String) to create and extend.

mappings - Table name selector and mapping definitions. Use utility function TableProviderAPIHelper#addParameter(Parameters, String, String) to create and extend.

maxFailAttempts - Maximum failures before giving up. Anything < 1 for infinite attempts

waitSeconds - Time to wait after a failure before trying. Anything < 1 becomes the default of 120 seconds.

Throws:

LiveViewException

Since:

LiveView 1.6

See Also:

LiveViewConnection.TableProviderAPIHelper

removeTableProvider

void removeTableProvider(java.lang.String id)
                  throws LiveViewException

Deprecated. Use TableAdminManager, instead

Throws:

LiveViewException

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()

Returns:

A ServerUtilityDataProvider, which provides API to get utility data from the server.

Since:

2.1

getSendTupleInfo

SendTupleInfo getSendTupleInfo(StreamBaseURI sbUri,
                               java.lang.String targetInputStreamName,
                               java.lang.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,
                      java.lang.String targetInputStreamName,
                      Tuple tuple,
                      java.lang.String responseOutputStreamName,
                      Schema expectedResponseSchema,
                      long timeout,
                      java.util.concurrent.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

java.util.List<java.lang.Boolean> checkPermissions(java.util.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