/*
* Defines the interface of the LiveView Web API. Implementations vary as server-side resources and transport mechanics
* my change.
*/
;(function(window, $, LiveView, undefined){
'use strict';
var connections = {},
connectionCount = 0;
//Check for required libs/modules
if(!LiveView){
console.error('LiveView does not exist. Cannot create sub module LiveViewConnection');
return;
}
else if(!LiveView._internal){
console.error('LiveView._internal does not exist. Cannot create sub module LiveViewConnection');
return;
}
/* -------------------- API-accessible functionality --------------------*/
/** @alias LiveView.Connection.prototype */
var LiveViewConnectionAPI = { //$.extend not done here for jsdoc purposes
/**
* 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.
* @class Connection
* @memberOf LiveView
*/
Connection: Connection,
/**
* 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 {@link LiveView.Connection#subscribe|subscribe}.
* @class QuerySubscription
* @memberOf LiveView
* @param {Number} id The unique identifier for this subscription. This value will be set by the API.
* @param {LiveView.Connection} connection The connection on which the query is subscribed.
* @param {LiveView.Query} query The query string that was issued to the server.
* @param {Object} settings The settings that were used when subscribing to the query. This includes the callbacks and context provided for subscription events.
*/
QuerySubscription: QuerySubscription,
/**
* Connects to the LiveView server. If no settings are provided, the function will attempt to connect to the
* the host identified by the current window location via the path '/lv/client'. The protocols used by the
* LiveView connection will correspond to the protocol used by window.location. If window.location specifies
* HTTPS as its protocol, then commands issued to LiveView will also be sent via HTTPS and all traffic sent or
* received via WebSocket will also be done via a secure connection.
* @function connect
* @memberOf LiveView
* @param {Object} [settings] Object containing the settings for performing the connection
* @param {String} [settings.url] The URL of the LiveView server to connect to. The format of the url should be of the form: <span class="lvCode">http://hostname:port/path/to/lv/client</span> or <span class="lvCode">/path/to/lv/client</span>. For example: <span class="lvCode">http://localhost:10080/lv/client</span> or <span class="lvCode">/lv/client</span>. If a pathname is given as the URL, the API will attempt to connect to the host identified by the current window location. If no url is specified, the API will attempt to use '/lv/client'.
* @param {String} [settings.username] The username to use when authenticating with the LiveView server.
* @param {String} [settings.password] The password to use when authenticating with the LiveView server.
* @param {String} [settings.clientInfo] Additional information sent with the connection request that appears in LDM system tables as ClientInfo.
* @param {String} [settings.transportUrl] If your environment requires web socket data be sent and received via a host that is not the same as the one defined by the settings.url property, set the settings.transportUrl to be the web socket URL that the LiveView JS API should use when making the web socket connection (e.g. 'ws://my.wsproxy.net:9000'). Both normal and secure web socket URLs (i.e. those beginning with 'ws://' and 'wss://' respectively) are supported. This is considered an advanced setting and should not be changed in most scenarios. If you are deploying your application via cloud services, this setting may be required as some cloud service providers require web socket traffic be proxied via a specific port.
* @param {Function} [settings.onClose] 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 {@link LiveView.Connection|Connection} that was closed. The actor field will be "client", "browser", "server", or "unknown" depending on whether the client, browser (typically the result of the user clicking refresh), server, or an error caused the closing of the connection. The error field (if set) is an {@link LiveView.Error|Error}. The presence of the error field indicates an error took place and the connection was closed as a result.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onStreamError] Callback function to invoke if an error occurs in the underlying streaming connection to LiveView. The callback will be passed an {@link LiveView.Error|Error} object containing details about what went wrong. You can change this function later by setting the transport.onStreamError property of your connection instance.
* @param {Function} [settings.onSuccess] Callback function to invoke upon successful connection to LiveView. The callback function will be passed an object containing one field: connection:{@link LiveView.Connection|Connection} The new connection that was created.
* @param {Function} [settings.onError] Callback function to invoke upon failure to connect to LiveView. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<LiveView.Connection>} -- Promise representing the result of the connect function. Upon successful connection, the promise will be resolved and the resolution handler function will be passed a {@link LiveView.Connection|Connection} object that represents the opened connection. If the connection fails, the promise will be rejected and the rejection handler will be passed an {@link LiveView.Error|Error} object with details about what went wrong.
*/
connect: connect,
/**
* Closes all currently active LiveView connections
* @function closeAllConnections
* @memberOf LiveView
* @param {Object} settings Object containing the settings for performing the connection
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] Callback function to invoke upon successful closure of all connections. The callback function will not be passed any parameters.
* @param {Function} [settings.onError] Callback function to invoke upon failure to close all connections. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<void>} -- Promise representing the result of the closeAllConnections function. Upon successfully closing all connections, the promise will be resolved and the resolution handler will be invoked with no arguments. If closing connections fails, the promise will be rejected and the rejection handler will be passed an {@link LiveView.Error|Error} object with details about what went wrong.
*/
closeAllConnections: closeAllConnections,
/**
* @memberOf LiveView.Connection
* @readonly
* @enum {String}
*/
CONNECTION_STATUS: {
/**
* The connection is closed.
*/
CLOSED: 'closed',
/**
* The connection is in the process of closing. Most likely, it is waiting on resource clean-up and/or server confirmation of closure.
*/
CLOSING: 'closing',
/**
* The connection is open.
*/
OPEN: 'open',
/**
* The connection is in the process of opening. Most likely, it is waiting for the server to acknowledge connection.
*/
OPENING: 'opening',
/**
* 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.
*/
ERROR: 'error'
}
};
$.extend(LiveView, LiveViewConnectionAPI);
/* -------------------- LiveView Connection Module Implementations --------------------*/
function Connection(settings){
if(!(this instanceof Connection)){ return new Connection(settings); }
this.settings = settings;
/**
* The unique identifier for this connection. Its value is automatically set upon successful connection.
* @memberOf LiveView.Connection.prototype
* @member {String} id
*/
this.id = null;
/**
* The username used for authenticating with the LiveView server. Its value is automatically set upon successful
* connection.
* @memberOf LiveView.Connection.prototype
* @member {String} username
*/
this.username = null;
/**
* The URL to which this connection is made.
* @memberOf LiveView.Connection.prototype
* @member {String} url
*/
this.url = null;
/**
* The connection status for this connection.
* @memberOf LiveView.Connection.prototype
* @member {LiveView.Connection.CONNECTION_STATUS} status
*/
this.status = null;
/**
* 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 {@link LiveView.Connection|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 {@link LiveView.Error|Error}. The presence of the error field indicates an
* error took place and the connection was closed as a result.
* @member {Function} onClose
* @memberOf LiveView.Connection.prototype
*/
this.onClose = function(){};
}
/** @alias LiveView.Connection.prototype */
Connection.prototype = {
constructor: Connection,
/**
* Closes this connection cleanly, canceling all active queries running via this connection.
* @function close
* @memberOf LiveView.Connection.prototype
* @param {Object} [settings] Object that defines callbacks and callback context for handling connection closure.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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.
* @param {Function} [settings.onError] 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 {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<void>} -- 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 {@link LiveView.Error|Error} object containing details about what went wrong.
*/
close: function(settings){},
/**
* Performs a one-time get of table metadata for the (optionally) specified tables.
* @function getTables
* @memberOf LiveView.Connection.prototype
* @param {Object} [settings] Object containing the settings for getting table metadata
* @param {Array} [settings.tableNames] 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.
* @param {boolean} [settings.includeSystemTables] Flag indicating whether or not to include LiveView system tables in the results. Default is false.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.Table|Table} objects.
* @param {Function} [settings.onError] Callback function to invoke upon failure to retrieve table metadata. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Table|Table} objects. If there is an error, the promise will be rejected and the rejection handler function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
*/
getTables: function(settings){},
/**
* Validates a query and (if valid) returns various information describing the characteristics of the query.
* @function parseQuery
* @memberOf LiveView.Connection.prototype
* @param {LiveView.Query|String} query A {@link LiveView.Query|Query} object or query String to be parsed.
* @param {Object} [settings] Object containing the settings for parsing the query
* @param {Object} [settings.tableName] Explicitly providing the table name can help LDM properly parse the query. <strong>If querying a table that is not LiveQL compatible, specifying the table name is highly recommended.</strong>
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] Callback function to invoke upon validation of the query. The callback function will be passed an object with field: queryProperties. The queryProperties field is a {@link LiveView.QueryProperties|QueryProperties} object that contains information about the parsed query.
* @param {Function} [settings.onError] Callback function to invoke upon failure to validate the query. This can occur due to an invalid query or due to an internal error. Either way, the callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<LiveView.QueryProperties>} -- Promise representing the result of the parseQuery function. On success, the promise resolution handler function will be passed an object with field: queryProperties. The queryProperties field is a {@link LiveView.QueryProperties|QueryProperties} object that contains information about the parsed query. If there is an error (perhaps because the query failed to validate), the promise will be rejected and the rejection handler function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
*/
parseQuery: function(query, settings){},
/**
* 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.
* @function execute
* @memberOf LiveView.Connection.prototype
* @param {LiveView.Query} query Defines the query to perform.
* @param {Object} [settings] Object containing the optional settings for query execution.
* @param {Object} [settings.tableName] Explicitly providing the table name can help LDM properly parse and execute the query. <strong>If querying a table that is not LiveQL compatible, specifying the table name is highly recommended.</strong>
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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
* @param {Function} [settings.onProgress] Callback function to invoke upon query progress events. The callback function will be passed an object with field: tuple. The tuple field is the {@link LiveView.Tuple|Tuple} that was added to the query result set.
* @param {Function} [settings.onError] Callback function to invoke upon failure to perform query. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Schema|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 {@link LiveView.Error|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 {@link LiveView.Tuple|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 {@link LiveView.Error|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);
* }
* }
* );
* }
*
*/
execute: function(query, settings){},
/**
* Performs a continuous LiveView query that will be updated with any changes in query results.
* @function subscribe
* @memberOf LiveView.Connection.prototype
* @param {LiveView.Query} query Defines the query to perform.
* @param {Object} [settings] Object containing the optional settings for query subscription.
* @param {Object} [settings.tableName] Explicitly providing the table name can help LDM properly parse and execute the query. <strong>If querying a table that is not LiveQL compatible, specifying the table name is highly recommended.</strong>
* @param {Function} [settings.onInsert] 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 {@link LiveView.QuerySubscription|QuerySubscription} for which a tuple has been added. The tuple field is the {@link LiveView.Tuple|Tuple} that was added.
* @param {Function} [settings.onUpdate] 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 {@link LiveView.QuerySubscription|QuerySubscription} for which a tuple has been updated. The tuple field is a {@link LiveView.Tuple|Tuple} that contains updated information. The tuple is a "delta tuple", meaning that its filedMap only contains those fields that have updated values.
* @param {Function} [settings.onDelete] 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 {@link LiveView.QuerySubscription|QuerySubscription} for which a tuple has been deleted. The tuple field is the {@link LiveView.Tuple|Tuple} that was deleted.
* @param {Function} [settings.onSnapshotStart] 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 {@link LiveView.QuerySubscription|QuerySubscription} for which the snapshot has started. The schema field contains a {@link LiveView.Schema|Schema} that defines the query's schema.
* @param {Function} [settings.onSnapshotEnd] 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 {@link LiveView.QuerySubscription|QuerySubscription} for which the snapshot has ended.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.QuerySubscription|QuerySubscription} that represents the created subscription.
* @param {Function} [settings.onError] 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 {@link LiveView.QuerySubscription|QuerySubscription} that caused the error. The error field is an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.QuerySubscription|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 {@link LiveView.Error|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);
* }
* );
* }
*
*/
subscribe: function(query, settings){},
/**
* Unsubscribes from an active QuerySubscription.
* @function unsubscribe
* @memberOf LiveView.Connection.prototype
* @param {LiveView.QuerySubscription} querySubscription The active QuerySubscription to close
* @param {Object} [settings] Object containing the settings for unsubscribing from the query.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.QuerySubscription|QuerySubscription} that successfully unsubscribed.
* @param {Function} [settings.onError] 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 {@link LiveView.QuerySubscription|QuerySubscription} that failed to unsubscribe. The error field is an {@link LiveView.Error|Error} with details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.QuerySubscription|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 {@link LiveView.QuerySubscription|QuerySubscription} that failed to unsubscribe. The error field is an {@link LiveView.Error|Error} with details about what went wrong.
*/
unsubscribe: function(querySubscription, settings){},
/**
* Unsubscribes from all active query subscriptions.
* @function unsubscribeAll
* @memberOf LiveView.Connection.prototype
* @param {Object} [settings] Object containing the settings for unsubscribing.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] Callback function to invoke upon successfully unsubscribing. The callback will not be passed any parameters.
* @param {Function} [settings.onError] Callback function to invoke upon failure to unsubscribe. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Error|Error} object containing details about what went wrong.
*/
unsubscribeAll: function(settings){},
/**
* 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.
* @function deleteRows
* @memberOf LiveView.Connection.prototype
* @param {String} tableName The name of the table upon which the deletion query will be performed.
* @param {String} predicate 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.
* @param {Object} [settings] Object containing the optional settings for the delete function.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] Callback function to invoke upon successfully executing the deletion query. No arguments will be passed to the callback function.
* @param {Function} [settings.onError] Callback function to invoke upon failure to perform deletion query. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Error|Error} object containing details about what went wrong.
*/
deleteRows: function(tableName, predicate, settings){},
/**
* Get information about the input and/or output streams at a given SB URI.
* @function getStreams
* @memberOf LiveView.Connection.prototype
* @param {Object} [settings] An object containing optional parameters for the getStreams function
* @param {String} [settings.sbUri = 'sb://localhost:10000'] The URI for the StreamBase host where the streams are located.
* @param {RegExp|Array<String>} [settings.inputStreamFilter] A filter to apply to the set of input stream names. Meta-data for an input stream will only be returned if the corresponding input stream name passes the filter. If a RegExp is provided, the input stream names must match the RegExp. If an array of Strings is provided, meta-data will only be returned for the input names that are contained in the array. If left blank, all input stream meta-data will be returned.
* @param {RegExp|Array<String>} [settings.outputStreamFilter] A filter to apply to the set of output stream names. Meta-data for an output stream will only be returned if the corresponding output stream name passes the filter. If a RegExp is provided, the output stream names must match the RegExp. If an array of Strings is provided, meta-data will only be returned for the output names that are contained in the array. If left blank, all output stream meta-data will be returned.
* @param {Boolean} [settings.includeSchemas = false] A flag indicating whether or not to fetch stream schemas as a part of the returned stream meta-data. A true value will result in schema information being included in the returned meta-data for each stream. Note that if enabled, this will potentially make many additional calls to the server as one call is made for each stream. To avoid wasteful processing and network traffic overhead, it is strongly advised that inputStreamFilter and/or outputStreamFilter be used when fetching stream schemas.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] Callback function to call after successfully getting stream information. The callback function will be passed an object with two fields: inputStreams and outputStreams. The inputStreams and outputStreams fields will be a key-value object map where the key is the stream name and the value is an object containing meta-data about the stream. Meta-data for both input and output streams will contain a "schema" field of type {@link LiveView.Schema|Schema}, if the includeSchemas flag was set to true.
* @param {Function} [settings.onError] Callback function to call if there was an error while getting the streams. The callback function will be passed an object containing field: error. The error field is an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- Promise representing the result of the getStreams function. Upon success, the promise resolution handler is passed an object with with two fields: inputStreams and outputStreams. The inputStreams and outputStreams fields will be a key-value object map where the key is the stream name and the value is an object containing meta-data about the stream. Meta-data for both input and output streams will contain a "schema" field of type {@link LiveView.Schema|Schema}, if the includeSchemas flag was set to true. If getting the streams fails, the promise will be rejected and the rejection handler will be passed an {@link LiveView.Error|Error} object with details about what went wrong.
* @example
* //Log all SB stream names to console
* lvConnection.getStreams().then(
* function(result){
* console.log('Input Streams:');
* Object
* .keys(result.inputStreams)
* .forEach(function(inStreamName){
* console.log(inStreamName);
* });
*
* console.log('Output Streams:');
* Object
* .keys(result.outputStreams)
* .forEach(function(outStreamName){
* console.log(outStreamName);
* });
* }
* );
*
* //Pretty-print the meta-data (including schema) for the ItemsSales.DataIn stream
* lvConnection.getStreams({inputStreamFilter: ['ItemsSales.DataIn'], outputStreamFilter: [], includeSchemas: true}).then(
* function(result){
* console.log(JSON.stringify(result.inputStreams, null, ' '));
* }
* );
*/
getStreams: function(settings){},
/**
* 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.
* @function getStreamSchemas
* @memberOf LiveView.Connection.prototype
* @deprecated since version 1.2, please use {@link LiveView.Connection.getStreams}
* @param {String} inputStream The name of the input stream.
* @param {String} [outputStream] The name of the output stream. If not provided, the resulting outputSchema will be an empty object.
* @param {Object} [settings] An object containing the parameters for getStreamSchemas.
* @param {String} [settings.serverUri] The StreamBase URI where the streams are located (e.g. "sb://localhost:10000/").
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.Schema|Schema} that describes the schema that should be applied to tuples being sent to the specified inputStream. The outputSchema field will be a {@link LiveView.Schema|Schema} that describes the schema that applies to tuples being received via the specified outputStream.
* @param {Function} [settings.onError] 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 {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Schema|Schema} that describes the schema that should be applied to tuples being sent to the specified inputStream. The outputSchema field will be a {@link LiveView.Schema|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 {@link LiveView.Error|Error} object with details about what went wrong.
*/
getStreamSchemas: function(inputStream, outputStream, settings){},
/**
* 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.
* @function sendTuple
* @memberOf LiveView.Connection.prototype
* @param {LiveView.Tuple} tuple The tuple object to send.
* @param {String} inputStream The name of the input stream to send the tuple to.
* @param {String} outputStream 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.
* @param {Object} [settings] An object containing the parameters for sendTuple
* @param {String} [settings.serverUri] The StreamBase URI to send the Tuple to
* @param {Number} [settings.timeout] 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.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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.
* @param {Function} [settings.onError] 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 {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Error|Error} object with details about what went wrong.
*/
sendTuple: function(tuple, inputStream, outputStream, settings){},
/**
* Gets all alert rules for the specified owner. If no owner is specified, the function fetches rules for the current user.
* @function getAlertRules
* @memberOf LiveView.Connection.prototype
* @param {Object} [settings] An object containing the optional parameters for getAlertRules.
* @param {String} [settings.owner] 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.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.AlertRule}s that were fetched.
* @param {Function} [settings.onError] Callback function to call on failure to retrieve alert rules. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.AlertRule}s that were fetched. If fetching the alert rules fails, the promise will be rejected and the rejection handler will be passed an {@link LiveView.Error|Error} object with details about what went wrong.
*/
getAlertRules: function(settings){},
/**
* Adds an AlertRule to the LiveView server.
* @function addAlertRule
* @memberOf LiveView.Connection.prototype
* @param {LiveView.AlertRule} 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.
* @param {Object} [settings] An object containing the optional parameters for addAlertRule.
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.AlertRule|AlertRule} as it was added by the LiveView server.
* @param {Function} [settings.onError] Callback function to call on failure to add the AlertRule. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.AlertRule|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 {@link LiveView.Error|Error} object with details about what went wrong.
*/
addAlertRule: function(alertRule, settings){},
/**
* Updates an existing AlertRule at the LiveView server.
* @function updateAlertRule
* @memberOf LiveView.Connection.prototype
* @param {LiveView.AlertRule} 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.
* @param {Object} [settings] An object containing the optional parameters for updateAlertRule
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.AlertRule|AlertRule} that was updated at the LiveView server.
* @param {Function} [settings.onError] Callback function to call on failure to update the AlertRule. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.AlertRule|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 {@link LiveView.Error|Error} object with details about what went wrong.
*/
updateAlertRule: function(alertRule, settings){},
/**
* 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.
* @function deleteAlertRule
* @memberOf LiveView.Connection.prototype
* @param {Number} alertRuleId The id of the AlertRule to delete.
* @param {Object} [settings] An object containing the optional parameters for deleteAlertRule
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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.
* @param {Function} [settings.onError] Callback function to call on failure to delete the AlertRule. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Error|Error} object with details about what went wrong.
*/
deleteAlertRule: function(alertRuleId, settings){},
/**
* Validates an AlertRule at the LiveView server.
* @function validateAlertRule
* @memberOf LiveView.Connection.prototype
* @param {LiveView.AlertRule} alertRule The AlertRule to validate.
* @param {Object} [settings] An object containing the optional parameters for validateAlertRule
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.AlertRule|AlertRule} that was successfully validated.
* @param {Function} [settings.onError] Callback function to call on failure to validate the AlertRule. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.AlertRule|AlertRule} that was successfully validated. If the rule is invalid, the promise will be rejected and the rejection handler will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
*/
validateAlertRule: function(alertRule, settings){}
};
function QuerySubscription(id, connection, query, settings){
if(!(this instanceof QuerySubscription)){
return new QuerySubscription(id, connection, query, settings);
}
/**
* The unique identifier for this subscription. This value will be set by the API.
* @memberOf LiveView.QuerySubscription
* @instance
* @member {Number} id
*/
this.id = id;
/**
* The connection on which the query is subscribed.
* @memberOf LiveView.QuerySubscription
* @instance
* @member {LiveView.Connection} connection
*/
this.connection = connection;
/**
* The query object that represents the query that was issued to the server.
* @memberOf LiveView.QuerySubscription
* @instance
* @member {LiveView.Query} query
*/
this.query = $.extend(true, new LiveView.Query(), query);
/**
* The settings for the subscription (i.e. those that were passed when invoking subscribe)
* @memberOf LiveView.QuerySubscription
* @instance
* @member {Object} settings
*/
this.settings = settings;
/**
* The status object that represents the query that was issued to the server.
* @memberOf LiveView.QuerySubscription
* @instance
* @member {LiveView.QuerySubscription.Status} status
*/
this.status = QuerySubscription.Status.CLOSED;
/**
* The query's key fields as an array of field names.
* @memberOf LiveView.QuerySubscription
* @instance
* @member {Array<String>} keyFields
*/
this.keyFields = [];
/**
* A flag indicating whether or not the query was issued against a native LiveView Table. Queries against tables
* that do not use LiveView as their table data provider will have isLvQuery set to false.
* @memberOf LiveView.QuerySubscription
* @instance
* @member {boolean} isLvQuery
*/
this.isLvQuery = true;
}
/** @alias LiveView.QuerySubscription.prototype */
QuerySubscription.prototype = {
constructor: QuerySubscription,
/**
* 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.
* @function
* @memberOf LiveView.QuerySubscription.prototype
* @param {Object} parameters 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. <span style="lvCode">{'@priceMin':100, '@lastUpdated':1415230518223}</span>).
* @param {Object} [settings] Object specifying additional settings for the applyParameters function
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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).
* @param {Function} [settings.onError] Callback function to invoke upon failure to apply parameters to the query. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.Error|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});
* }
*
*/
applyParameters: function(parameters, settings){},
/**
* Closes the query maintained by this QuerySubscription.
* @function
* @memberOf LiveView.QuerySubscription.prototype
* @param {Object} [settings] Object specifying additional, optional settings for the close function
* @param {Object} [settings.context] 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.
* @param {Function} [settings.onSuccess] 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 {@link LiveView.QuerySubscription|QuerySubscription} that successfully closed.
* @param {Function} [settings.onError] Callback function to invoke upon failure to close the query subscription. The callback function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
* @returns {Promise<Object>} -- 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 {@link LiveView.QuerySubscription|QuerySubscription} that successfully closed. If there is an error, the promise will be rejected and the rejection handler function will be passed an {@link LiveView.Error|Error} object containing details about what went wrong.
*/
close: function(settings){}
};
/**
* @memberOf LiveView.QuerySubscription
* @readonly
* @enum {Object}
*/
LiveView.QuerySubscription.Status = {
/**
* 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
*/
STARTING: {string: 'STARTING', value: 0},
/**
* The query has started and is running
*/
ACTIVE: {string: 'ACTIVE', value: 1},
/**
* The query is in the process of updating its parameters
*/
UPDATING: {string: 'UPDATING', value: 2},
/**
* 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
*/
CLOSING: {string: 'CLOSING', value: 3},
/**
* The query is not active.
*/
CLOSED: {string: 'CLOSED', value: 4},
/**
* There was an error that occurred while running the query
*/
ERROR: {string: 'ERROR', value: 5}
};
function connect(settings){
settings = settings || {};
if(!settings.url){
settings.url = '/lv/client';
}
var connection = new LiveView._internal.StreamingConnection({
url: settings.url,
transportUrl: settings.transportUrl,
onStreamError: settings.onStreamError,
onClose: settings.onClose,
context: settings.context
});
connections[connectionCount] = connection;
return connection.open({
username: settings.username,
password: settings.password,
context: settings.context || window,
onSuccess: settings.onSuccess,
onError: settings.onError,
clientInfo: settings.clientInfo || null
})
.then(
function(){
return connection;
}
);
}
function closeAllConnections(settings){
var closeDeferreds = [];
settings = settings || {};
for(var connectionId in connections){
if(connections.hasOwnProperty(connectionId) && (typeof connections[connectionId].close === 'function')){
closeDeferreds.push(connections[connectionId].close());
}
}
return $.when.apply(null, closeDeferreds)
.then(
function(){
LiveView._internal.Util.invokeCallback(settings.onSuccess, settings.context, {});
},
function(error){
LiveView._internal.Util.invokeCallback(settings.onError, settings.context, {error:error});
}
);
}
}(window, jQuery, window.LiveView));