Class: QuerySubscription

LiveView. QuerySubscription

new LiveView.QuerySubscription(id, connection, query, settings)

Object that represents a query that has been or is currently being executed at the server. This constructor is internal to LiveView and should not be invoked directly. QuerySubscriptions will be created and returned as the result of calling subscribe.
Name Type Description
id Number The unique identifier for this subscription. This value will be set by the API.
connection LiveView.Connection The connection on which the query is subscribed.
query LiveView.Query The query string that was issued to the server.
settings Object The settings that were used when subscribing to the query. This includes the callbacks and context provided for subscription events.

Members

idNumber

The unique identifier for this subscription. This value will be set by the API.
The connection on which the query is subscribed.
The query object that represents the query that was issued to the server.

settingsObject

The settings for the subscription (i.e. those that were passed when invoking subscribe)
The status object that represents the query that was issued to the server.

static,readonlyLiveView.QuerySubscription.StatusObject

Properties:
Name Type Default Description
STARTING Object OBJECTLIT The query is in the process of starting up. Once the query has been acknowledged by the server as started and the necessary listeners have been linked, status will transition to ACTIVE
ACTIVE Object OBJECTLIT The query has started and is running
UPDATING Object OBJECTLIT The query is in the process of updating its parameters
CLOSING Object OBJECTLIT The query is in the process of closing. Once query closure has been acknowledged by the server and any necessary cleanup has been performed, status will transition to CLOSED
CLOSED Object OBJECTLIT The query is not active.
ERROR Object OBJECTLIT There was an error that occurred while running the query

Methods

applyParameters(parameters, settings){Promise.<Object>}

Applies the provided parameters to the query that is maintained by this QuerySubscription. The process terminates the currently executing query and reinitializes it with the given parameters. This QuerySubscription's fields will not change in the process (i.e. the query id, callbacks, etc.). Only the contained Query's parameters will be modified. The same callbacks that were used for the initial query will still be used for the re-parameterized query.
Name Type Description
parameters Object Map of parameter token to parameter value to be applied to the query. Users are essentially free to define the token used to identify a parameter as they wish. The query string is generated using regular expression substitution, so avoidance of regular expression special characters is recommended as it will likely cause unexpected behavior. The '@' character as a parameter prefix works well (e.g. {'@priceMin':100, '@lastUpdated':1415230518223}).
settings Object optional Object specifying additional settings for the applyParameters 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 successful application of parameters to the query. The callback will be passed an object with field: subscription. The subscription field is this query subscription (i.e. the one whose parameters were applied).
onError function optional Callback function to invoke upon failure to apply parameters to the query. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the applyParameters function. On success, the promise resolution handler function will be passed an object with field: subscription. The subscription field is this query subscription (i.e. the one whose parameters were applied). If the applying parameters fails, the promise will be rejected and the rejection handler will be passed an Error object containing details about what went wrong.
Example
 //First connect to LiveView
 var lvConnection, subscribedQuery;
 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 sku, lastSoldPrice FROM ItemsSales WHERE sku = @itemName', {'@itemName':'\'Teddy Bear\''}),
         {
             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){
             subscribedQuery = result.subscription;
             //In normal applications, triggering of query update is likely to come from a user who clicked a
             //button, selected something from a drop-down, etc.
             //Here, we wait 2 seconds and then apply new parameters to the query
             setTimeout(function(){updateQuery('\'Cell Phone\'')}, 2000);
         },
         function(error){
             console.log('Something went wrong: ' + error.message);
         }
     );
 }

 function updateQuery(itemName){
     if(!subscribedQuery){ return; } //query isn't ready
     console.log('================ Applying Parameters ===============');
     subscribedQuery.applyParameters({'@itemName':itemName});
 }

close(settings){Promise.<Object>}

Closes the query maintained by this QuerySubscription.
Name Type Description
settings Object optional Object specifying additional, optional settings for the close 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 successful closure of the subscription. The callback will be passed an object with field: subscription. The subscription field is the QuerySubscription that successfully closed.
onError function optional Callback function to invoke upon failure to close the query subscription. The callback function will be passed an Error object containing details about what went wrong.
Returns:
Promise representing the result of the close function. On success, the promise resolution handler function will be passed an object with field: subscription. The subscription field is the QuerySubscription that successfully closed. 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.