Class: Connection

LiveView. Connection

new LiveView.Connection()

liveview-connection.js, line 25
LiveView Connection constructor. This constructor is internal to LiveView and cannot/should not be instantiated directly. Calls to LiveView.connect() will create an appropriate Connection and return a Connection object as a reference to the connection.

Members

idString

The unique identifier for this connection. Its value is automatically set upon successful connection.

urlString

The URL to which this connection is made.

statusLiveView.Connection.CONNECTION_STATUS

The connection status for this connection.

onClosefunction

Callback function to invoke upon closure of the connection (whether in error or as expected). The callback will be passed an object containing two or three fields: connection, actor, and (optionally) error. The connection field will be the Connection that was closed. The actor field will either be "client" or "server" depending on whether the client or server initiated the closing of the connection. The error field (if set) is an Error. The presence of the error field indicates an error took place and the connection was closed as a result.

static,readonlyLiveView.Connection.CONNECTION_STATUSString

Properties:
Name Type Default Description
CLOSED String closed The connection is closed.
CLOSING String closing The connection is in the process of closing. Most likely, it is waiting on resource clean-up and/or server confirmation of closure.
OPEN String open The connection is open.
OPENING String opening The connection is in the process of opening. Most likely, it is waiting for the server to acknowledge connection.
ERROR String error Something went wrong with the connection. A description of the cause should be available via the promise rejection handler or onError callback function of the error-causing function call.

Methods

close(settings){Promise.<void>}

liveview-connection.js, line 154
Closes this connection cleanly, canceling all active queries running via this connection.
Name Type Description
settings Object optional Object that defines callbacks and callback context for handling connection closure.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to invoke upon successfully closing the connection. This function will be invoked after this connection's onClose handler has been invoked. It will not be passed any parameters.
onError function optional Callback function to invoke upon failure to close the connection. This function will be invoked after any this connection's onClose handler has been invoked. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the close function. Once resources have been cleaned and the server has acknowledged closure, the promise will resolve with no arguments. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.

getTables(settings){Promise.<Object>}

liveview-connection.js, line 166
Performs a one-time get of table metadata for the (optionally) specified tables.
Name Type Description
settings Object optional Object containing the settings for getting table metadata
Name Type Description
tableNames Array optional The names of the tables to get meta data for. If null or undefined, metadata for all tables will be returned. The default value is null.
includeSystemTables boolean optional Flag indicating whether or not to include LiveView system tables in the results. Default is false.
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to invoke upon successful receipt of table metadata. The callback function will be passed an object with field: tables. The tables field is an array of Table objects.
onError function optional Callback function to invoke upon failure to retrieve table metadata. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the getTables function. On success, the promise resolution handler function will be passed an object with field: tables. The tables field is an array of Table objects. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.

execute(query, settings){Promise.<Object>}

liveview-connection.js, line 180
Performs a one-time execution of a query. This is an easy way to quickly get table data without having to set up a query subscription. Technically, this call subscribes to a snapshot-only query and buffers results until the end-snapshot event is received. Once the end-snapshot event is received, query resources are cleaned and the query schema and buffered result data are returned via promise resolution and/or the onSuccess callback function.
Name Type Description
query LiveView.Query Defines the query to perform.
settings Object optional Object containing the optional settings for query execution.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to invoke upon successful receipt of query results. The callback function will be passed an object with fields: schema and data. The schema field defines the executed query's schema. The data field contains the query results as an array of tuples in the order they were returned by the query
onProgress function optional Callback function to invoke upon query progress events. The callback function will be passed an object with field: tuple. The tuple field is the Tuple that was added to the query result set.
onError function optional Callback function to invoke upon failure to perform query. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the execute function. On success, the promise resolution handler function will be passed an object with two fields: schema and data. The schema field is a Schema that defines the query's schema. The data field contains the query results as an array of tuples in the order they were returned by the query. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong. When a new row is added to the query execution's result set, the promise's progress handler will be passed an object with field: tuple. The tuple field is the Tuple that was added to the query result set. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.
Example
 //First connect to LiveView
 var lvConnection;
 LiveView.connect({url: '/lv/client'}).then(
     function(connection){
         //once connected, keep the reference to the connection and execute queries
         lvConnection = connection;
         executeQueries();
     }
 );
 function executeQueries(){
     //With Promises
     lvConnection.execute(
         new LiveView.Query('SELECT * FROM ItemsSales WHERE lastSoldPrice > 100')
     )
     .then(
         function(result){
             console.log('Query execution using promise/deferred finished');
             console.log('Got schema:');
             console.log(result.schema);
             console.log('Got data:');
             console.log(result.data);
         },
         function(error){
             console.log('Something went wrong: ' + error.message);
         }
     );

     //With Callbacks
     lvConnection.execute(
         new LiveView.Query('SELECT * FROM ItemsSales WHERE lastSoldPrice > 100'),
         {
             context: window,
             onSuccess: function(result){
                 console.log('Query execution using callbacks finished');
                 console.log('Got schema:');
                 console.log(result.schema);
                 console.log('Got data:');
                 console.log(result.data);
             },
             onError: function(error){
                 console.log('Something went wrong: ' + error.message);
             }
         }
     );
 }

deleteRows(tableName, predicate, settings){Promise.<Object>}

liveview-connection.js, line 245
Performs a deletion query. This function tells the LiveView server to remove all rows from the provided table that satisfy the conditions specified in the predicate. If no predicate is given, or if the predicate is an empty string, then all rows in the given table will be removed. Note that the operation will not return the rows that were removed. A separate query on the same table that monitors delete events can be used to monitor which rows are removed.
Name Type Description
tableName String The name of the table upon which the deletion query will be performed.
predicate String The predicate string that defines the conditions to use when determining whether or not to remove a row from the table. See the "LiveQL Reference" guide in the LiveView documentation for more details on how to construct predicate strings.
settings Object optional Object containing the optional settings for the delete function.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to invoke upon successfully executing the deletion query. No arguments will be passed to the callback function.
onError function optional Callback function to invoke upon failure to perform deletion query. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the deleteRows function. On success, the promise resolution handler function will be invoked with no arguments. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.

subscribe(query, settings){Promise.<Object>}

liveview-connection.js, line 263
Performs a continuous LiveView query that will be updated with any changes in query results.
Name Type Description
query LiveView.Query Defines the query to perform.
settings Object optional Object containing the optional settings for query subscription.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onInsert function optional Callback function to invoke upon receipt of new query data. The callback function will be passed an object containing fields: subscription and tuple. The subscription field contains the QuerySubscription for which a tuple has been added. The tuple field is the Tuple that was added.
onUpdate function optional Callback function to invoke when an update is received for the query. The callback function will be passed an object containing fields: subscription and tuple. The subscription field contains the QuerySubscription for which a tuple has been updated. The tuple field is a Tuple that contains updated information. The tuple is a "delta tuple", meaning that its filedMap only contains those fields that have updated values.
onDelete function optional Callback function to invoke upon deletion of query data. The callback function will be passed an object containing fields: subscription and tuple. The subscription field contains the QuerySubscription for which a tuple has been deleted. The tuple field is the Tuple that was deleted.
onSnapshotStart function optional Callback function to invoke upon receipt of the begin_snapshot query event. The callback function will be passed an object containing fields: subscription and schema. The subscription field contains the QuerySubscription for which the snapshot has started. The schema field contains a Schema that defines the query's schema.
onSnapshotEnd function optional Callback function to invoke upon receipt of the end_snapshot query event. The callback function will be passed an object containing field: subscription. The subscription field contains the QuerySubscription for which the snapshot has ended.
onSuccess function optional Callback function to invoke upon successful subscription to the query. The callback function will be passed an object containing field: subscription. The subscription field is the QuerySubscription that represents the created subscription.
onError function optional Callback function to invoke if any subscription errors occur. This callback is particularly important because any data stream related issues will be communicated by its invocation. The callback function will be passed an object containing fields: subscription and error. The subscription field contains the QuerySubscription that caused the error. The error field is an Error object containing details about what went wrong.
Returns:
Promise representing the result of the subscribe function. On success, the promise resolution handler function will be passed an object with field: subscription. The subscription field is the QuerySubscription that represents the created subscription. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.
Example
 //First connect to LiveView
 var lvConnection;
 LiveView.connect({url: '/lv/client'}).then(
     function(connection){
         //once connected, keep the reference to the connection and run queries
         lvConnection = connection;
         runQueries();
     }
 );
 function runQueries(){
     lvConnection.subscribe(
         new LiveView.Query('SELECT * FROM ItemsInventory WHERE priceMax > 20'),
         {
             onSnapshotStart: function(event){
                 console.log('Snapshot started for query ' + event.subscription.id);
                 console.log('The query schema is:');
                 console.log(event.schema);
             },
             onInsert: function(event){
                 console.log('Query ' + event.subscription.id + ' got new data.');
                 console.log('The new tuple is:');
                 console.log(event.tuple);
             },
             onUpdate: function(event){
                 console.log('Query ' + event.subscription.id + ' updated data for tuple ' + event.tuple.id);
                 console.log('The updated tuple data is:');
                 console.log(event.tuple.fieldMap);
             },
             onDelete: function(event){
                 console.log('Query ' + event.subscription.id + ' deleted tuple ' + event.tuple.id);
             },
             onSnapshotEnd: function(event){
                 console.log('Snapshot ended for query ' + event.subscription.id);
             },
             onError: function(error){
                 console.log('There was an error while running query ' + event.subscription.id);
                 console.log('ERROR:');
                 console.log(error);
             }
         }
     )
     .then(
         function(result){
             console.log('Query subscription success');
             console.log('QuerySubscription for future reference:');
             console.log(result.subscription);
             console.log('Got schema:');
             console.log(result.schema);
         },
         function(error){
             console.log('Something went wrong: ' + error.message);
         }
     );
 }

unsubscribe(querySubscription, settings){Promise.<Object>}

liveview-connection.js, line 337
Unsubscribes from an active QuerySubscription.
Name Type Description
querySubscription LiveView.QuerySubscription The active QuerySubscription to close
settings Object optional Object containing the settings for unsubscribing from the query.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to invoke upon successfully unsubscribing from the query. The callback function will be passed an object with field: subscription. The subscription field is the QuerySubscription that successfully unsubscribed.
onError function optional Callback function to invoke upon failure to unsubscribe from the query. The callback function will be passed an object with fields: subscription and error. The subscription field is the QuerySubscription that failed to unsubscribe. The error field is an Error with details about what went wrong.
Returns:
Promise representing the result of the unsubscribe function. On success, the promise resolution handler function will be passed an object with field: subscription. The subscription field is the QuerySubscription that successfully unsubscribed. If there is an error, the promise will be rejected and the rejection handler function will be passed an object containing fields: subscription and error. The subscription field is the QuerySubscription that failed to unsubscribe. The error field is an Error with details about what went wrong.

unsubscribeAll(settings){Promise.<Object>}

liveview-connection.js, line 350
Unsubscribes from all active query subscriptions.
Name Type Description
settings Object optional Object containing the settings for unsubscribing.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to invoke upon successfully unsubscribing. The callback will not be passed any parameters.
onError function optional Callback function to invoke upon failure to unsubscribe. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the unsubscribeAll function. On success (i.e. when all subscriptions have successfully been unsubscribed), the promise will resolve with no arguments. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.

getStreamSchemas(inputStream, outputStream, settings){Promise.<Object>}

liveview-connection.js, line 363
Gets the schemas for tuples sent to the identified input stream and received from the identified output stream. Use of fully-qualified stream names is encouraged. If a fully-qualified stream name is not used, it will be assumed that the stream exists in the default container. Typically, however, application streams will not exist in the default container, which will likely result in problems.
Name Type Description
inputStream String The name of the input stream.
outputStream String optional The name of the output stream. If not provided, the resulting outputSchema will be an empty object.
settings Object optional An object containing the parameters for getStreamSchemas.
Name Type Description
serverUri String optional The StreamBase URI where the streams are located (e.g. "sb://localhost:10000/").
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than document.window.
onSuccess function optional Callback function to call when the stream schemas have been successfully fetched. The callback function will be passed an object with fields: inputSchema and outputSchema. The inputSchema field will be a Schema that describes the schema that should be applied to tuples being sent to the specified inputStream. The outputSchema field will be a Schema that describes the schema that applies to tuples being received via the specified outputStream.
onError function optional Callback function to call if getting the tuple schema fails. The callback function will be passed an object containing field: error. The error field is an Error object containing details about what went wrong.
Returns:
Promise representing the result of the getStreamSchemas function. Upon success, the promise resolution handler is passed an object with fields: inputSchema and outputSchema. The inputSchema field will be a Schema that describes the schema that should be applied to tuples being sent to the specified inputStream. The outputSchema field will be a Schema that describes the schema that applies to tuples being received via the specified outputStream. If getting the stream schemas fails, the promise will be rejected and the rejection handler will be passed an Error object with details about what went wrong.

sendTuple(tuple, inputStream, outputStream, settings){Promise.<Object>}

liveview-connection.js, line 381
Sends a tuple to the specified stream. Use of fully-qualified stream names is encouraged. If a fully- qualified stream name is not used, it will be assumed that the stream exists in the default container. Typically, however, application streams will not exist in the default container, which will likely result in problems.
Name Type Description
tuple LiveView.Tuple The tuple object to send.
inputStream String The name of the input stream to send the tuple to.
outputStream String The name of the output stream that the resultant tuple should be retrieved from. This can be null if no response is desired or expected.
settings Object optional An object containing the parameters for sendTuple
Name Type Description
serverUri String optional The StreamBase URI to send the Tuple to
timeout Number optional Number of milliseconds to wait to receive an output tuple. The default is 30,000 (30 seconds). The timeout will only be applied if an outputStream is provided. Upon timeout, the sendTuple promise will be rejected and (if provided) the onError callback will be invoked. The error passed will specify that timeout expiration was the reason for failure.
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than document.window.
onSuccess function optional Callback function to call after successfully sending the tuple. The callback function will be passed an object with field: tuple. The tuple field will be the resulting output tuple if an outputStream was specified. Otherwise, the tuple field will be null.
onError function optional Callback function to call if there was an error while sending the tuple. The callback function will be passed an object containing field: error. The error field is an Error object containing details about what went wrong.
Returns:
Promise representing the result of the sendTuple function. Upon success, the promise resolution handler is passed an object with field: tuple. The tuple field will be the resulting output tuple if an outputStream was specified. Otherwise, the tuple field will be null. If sending the tuple fails, the promise will be rejected and the rejection handler will be passed an Error object with details about what went wrong.

getAlertRules(settings){Promise.<Object>}

liveview-connection.js, line 401
Gets all alert rules for the specified owner. If no owner is specified, the function fetches rules for the current user.
Name Type Description
settings Object optional An object containing the optional parameters for getAlertRules.
Name Type Description
owner String optional If provided, getAlertRules will only fetch rules owned by the specified owner. If not provided, rules for the current user are fetched. If '*' is specified, rules for all owners will be returned.
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to call on successful fetch of alert rules. The callback function will be passed an object with field: rules. The rules field will be an array containing the LiveView.AlertRules that were fetched.
onError function optional Callback function to call on failure to retrieve alert rules. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the getAlertRules function. Upon success, the promise resolution handler is passed an object with field: rules. The rules field will be an array containing the LiveView.AlertRules that were fetched. If fetching the alert rules fails, the promise will be rejected and the rejection handler will be passed an Error object with details about what went wrong.

addAlertRule(alertRule, settings){Promise.<Object>}

liveview-connection.js, line 414
Adds an AlertRule to the LiveView server.
Name Type Description
alertRule LiveView.AlertRule The new AlertRule to add. Note: if an id value is specified for the AlertRule, it will be honored by the server. However, if an AlertRule already exists on the server with the provided id, that alert rule will be overwritten by the rule being sent. It is recommended that the id field be left undefined when adding a rule so that the server will assign an appropriate id.
settings Object optional An object containing the optional parameters for addAlertRule.
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to call when the AlertRule has successfully been added. The callback function will be passed an object with field: rule. The rule field will be the AlertRule as it was added by the LiveView server.
onError function optional Callback function to call on failure to add the AlertRule. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of addAlertRule function. Upon success, the promise resolution handler is passed an object with field: rule. The rule field will be the AlertRule as it was added by the LiveView server. Note that the server may modify the "id" field in the process. If adding the alert rule fails, the promise will be rejected and the rejection handler will be passed an Error object with details about what went wrong.

updateAlertRule(alertRule, settings){Promise.<Object>}

liveview-connection.js, line 427
Updates an existing AlertRule at the LiveView server.
Name Type Description
alertRule LiveView.AlertRule The updated version of the AlertRule. The id field must be set in order to successfully update the rule. If the id field is not set, or if the server has no rule with the specified id, the passed rule will be added.
settings Object optional An object containing the optional parameters for updateAlertRule
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to call when the AlertRule has successfully been updated. The callback function will be passed an object with field: rule. The rule field will be the AlertRule that was updated at the LiveView server.
onError function optional Callback function to call on failure to update the AlertRule. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the updateAlertRule function. Upon success, the promise resolution handler is passed an object with field: rule. The rule field will be the AlertRule that was updated at the LiveView server. If updating the alert rule fails, the promise will be rejected and the rejection handler will be passed an Error object with details about what went wrong.

deleteAlertRule(alertRuleId, settings){Promise.<Object>}

liveview-connection.js, line 440
Deletes an existing AlertRule at the LiveView server. Note this function will succeed even if the server has no record of an AlertRule with the provided alertRuleId.
Name Type Description
alertRuleId Number The id of the AlertRule to delete.
settings Object optional An object containing the optional parameters for deleteAlertRule
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to call when the AlertRule has successfully been deleted. The callback function will be passed an object with field: id. The id field contains the id of the AlertRule that was deleted.
onError function optional Callback function to call on failure to delete the AlertRule. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the deleteAlertRule function. Upon success, the promise resolution handler is passed an object containing field: id. The id field contains the id of the AlertRule that was deleted. If deleting the alert rule fails, the promise will be rejected and the rejection handler will be passed an Error object with details about what went wrong.

validateAlertRule(alertRule, settings){Promise.<Object>}

liveview-connection.js, line 453
Validates an AlertRule at the LiveView server.
Name Type Description
alertRule LiveView.AlertRule The AlertRule to validate.
settings Object optional An object containing the optional parameters for validateAlertRule
Name Type Description
context Object optional Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function optional Callback function to call when the AlertRule has successfully been validated. The callback function will be passed an object with field: rule. The rule field will be the AlertRule that was successfully validated.
onError function optional Callback function to call on failure to validate the AlertRule. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the validateAlertRule function. If the rule validates successfully, the promise will resolve and the promise resolution handler function is passed an object containing field: rule. The rule field will be the AlertRule that was successfully validated. If the rule is invalid, the promise will be rejected and the rejection handler will be passed an Error object containing details about what went wrong.