/**
* Important class. Runs SPARQL query against SPARQL
* endpoints.
*
* Dependencies:
*
* - sgvizler.util
* - sgvizler.namespace
* - sgvizler.registry
* - sgvizler.parser
* - sgvizler.loader
* - sgvizler.logger
* - sgvizler.defaults
* - jQuery
* - google.visualization
*
*
* Example of how to use the Query class:
*
* var sparqlQueryString = "SELECT * {?s ?p ?o} LIMIT 10",
* containerID = "myElementID",
* Q = new sgvizler.Query();
*
* // Note that default values may be set in the sgvizler object.
* Q.query(sparqlQueryString)
* .endpointURL("http://dbpedia.org/sparql")
* .endpointOutputFormat("json") // Possible values 'xml', 'json', 'jsonp'.
* .chartFunction("google.visualization.BarChart") // The name of the function to draw the chart.
* .draw(containerID); // Draw the chart in the designated HTML element.
*
* @class sgvizler.Query
* @constructor
* @param {Object} queryOptions
* @param {Object} chartOptions
* @since 0.5
**/
// Note: the parameter names in the documention are different just
// for better readability.
S.Query = function (queryOpt, chartOpt) {
/*global $ */
// Module dependencies:
var util = S.util,
getset = util.getset,
prefixesSPARQL = S.namespace.prefixesSPARQL,
registry = S.registry,
moduleGooVis = registry.GVIZ,
fDataTable = registry.DATATABLE,
parser = S.parser,
loadDependencies = S.loader.loadDependencies,
logger = S.logger,
defaults = S.defaults,
/* Constants for query formats (qf) */
qfXML = 'xml',
qfJSON = 'json',
qfJSONP = 'jsonp',
/**
* Contains properties relevant for query business. Get
* and set values using get/setter functions.
*
* Default values are found in sgvizler.defaults (these
* may be get/set with the get/setter function on the
* sgvizler class) and are loaded on construction---and
* get overwritten by properties in the constructed
* parameter.
* @property queryOptions
* @type Object
* @private
* @since 0.5
**/
queryOptions,
/**
* Contains properties relevant for chart drawing
* business. Get and set values using get/setter
* functions.
*
* Default values are found in sgvizler.defaults (these
* may be get/set with the get/setter function on the
* sgvizler class) and are loaded on construction---and
* get overwritten by properties in the constructed
* parameter.
* @property chartOptions
* @type Object
* @private
* @since 0.5
**/
chartOptions,
//TODO
listeners = {},
/**
* DataTable query results.
* @property dataTable
* @type google.visualization.DataTable
* @private
* @since 0.5
**/
dataTable,
/**
* The raw results as retuned by the endpoint.
* @property queryResult
* @type Object either XML or JSON
* @private
* @since 0.5
**/
queryResult,
/**
* The number of rows in the query results.
* @property noOfResults
* @type number
* @public
* @since 0.5
**/
noOfResults,
// TODO: better logging.
// processQueryResults = function (data) {
// var noRows = getResultRowCount(data);
// if (noRows === null) {
// S.logger.displayFeedback(this, "ERROR_UNKNOWN");
// } else if (noRows === 0) {
// S.logger.displayFeedback(this, "NO_RESULTS");
// } else {
// S.logger.displayFeedback(this, "DRAWING");
// return getGoogleJSON(data);
// }
// },
/**
* Add a url as an RDF source to be included in the SPARQL
* query in the `FROM` block.
* @method addFrom
* @public
* @param {String} url
* @since 0.5
**/
addFrom = function (url) {
queryOptions.froms.push(url);
},
/**
* Remove all registered FROMs.
*
* See also `addFrom`.
* @method clearFroms
* @public
* @since 0.5
**/
clearFroms = function () {
queryOptions.froms = [];
},
//// Getters/Setters
// TODO redefine query function setters when query is
// issued: only one query per Query.
/**
* Get query string.
* @method query
* @public
* @return {string}
*/
/**
* Set query string.
* @method query
* @public
* @param {string} queryString
* @chainable
*/
query = function (queryString) {
if (queryString !== undefined) {
clearFroms();
}
return getset('query', queryString, queryOptions, this);
},
/**
* Get endpoint URL.
* @method endpointURL
* @public
* @return {string}
* @since 0.5
**/
/**
* Set endpoint URL.
* @method endpointURL
* @public
* @param {string} url
* @chainable
* @example
* sgvizler.endpointURL('http://sparql.dbpedia.org');
* sets this Query object's endpoint to DBpedia.
* @since 0.5
**/
endpointURL = function (url) {
return getset('endpoint', url, queryOptions, this);
},
/**
* Get endpoint output format.
* @method endpointOutputFormat
* @public
* @return {string}
* @since 0.5
**/
/**
* Set endpoint output format. Legal values are `'xml'`,
* `'json'`, `'jsonp'`.
* @method endpointOutputFormat
* @public
* @param {string} format
* @chainable
* @since 0.5
**/
endpointOutputFormat = function (format) {
return getset('endpoint_output_format', format, queryOptions, this);
},
// TODO
endpointResultsURLPart = function (value) {
return getset('endpoint_results_urlpart', value, queryOptions, this);
},
/**
* Get URL to online SPARQL query validator.
* @method validatorURL
* @public
* @return {string}
* @since 0.5
**/
/**
* Set URL to online SPARQL query validator. Appending a
* SPARQL query to the end of this URL should give a page
* which validates the given query.
* @method validatorURL
* @public
* @param {string} url
* @chainable
* @since 0.5
* @example
* TODO
**/
validatorURL = function (url) {
return getset('validator_url', url, queryOptions, this);
},
// TODO
loglevel = function (value) {
return getset('loglevel', value, queryOptions, this);
},
// TODO
logContainer = function (value) {
return getset('logContainer', value, queryOptions, this);
},
/**
* Get the name of datatable preprocessing function.
* @method datatableFunction
* @public
* @return {string}
* @since 0.5
**/
/**
* Set the name of datatable preprocessing function. The
* function should be availble in the global object, or
* registered with dependencies in Sgvizler's registry;
* see TODO
* @method datatableFunction
* @public
* @param {string} functionName
* @chainable
* @since 0.5
**/
datatableFunction = function (functionName) {
return getset('datatable', functionName, queryOptions, this);
},
/**
* Get the name of chart function.
* @method chartFunction
* @public
* @return {string}
* @since 0.5
**/
/**
* Set the name of chart function. The function should be
* availble in the global object, or registered with
* dependencies in Sgvizler's registry; see TODO
* @method chartFunction
* @public
* @param {string} functionName
* @chainable
* @since 0.5
**/
chartFunction = function (functionName) {
return getset('chart', functionName, queryOptions, this);
},
/**
* Get the height of the chart container.
* @method chartHeight
* @public
* @return {string}
* @since 0.5
**/
/**
* Set the height of the chart container.
* @method chartHeight
* @public
* @param {number} height
* @chainable
* @since 0.5
**/
chartHeight = function (height) {
return getset('height', height, chartOptions, this);
},
/**
* Get the width of the chart container.
* @method chartWidth
* @public
* @return {string}
* @since 0.5
**/
/**
* Set the width of the chart container.
* @method chartWidth
* @public
* @param {number} width
* @chainable
* @since 0.5
**/
chartWidth = function (width) {
return getset('width', width, chartOptions, this);
},
/**
* Get the query string with prefixes added and encoded
* for URL insertion.
* @method getEncodedQuery
* @public
* @return {String}
* @since 0.5
**/
getEncodedQuery = function () {
return encodeURIComponent(prefixesSPARQL() + query());
},
/**
* Extends the query string by including the urls in
* `from` as `FROM` statements in the (SPARQL) `query`.
* @method insertFrom
* @private
* @since 0.5
**/
insertFrom = function () {
var i, len = queryOptions.froms.length,
from;
if (len) {
from = "";
for (i = 0; i < len; i += 1) {
from += 'FROM <' + queryOptions.froms[i] + '>\n';
}
query(query().replace(/((WHERE)?(\s)*\{)/i, '\n' + from + '$1'));
}
},
/**
* Sets and returns `noOfResults`, i.e., the number of
* rows in the query result.
* @method getResultRowCount
* @private
* @param {google.visualization.DataTable} dataTable
* @return {Number}
* @since 0.5
**/
getResultRowCount = function (dataTable) {
if (noOfResults === undefined) {
if (endpointOutputFormat() === qfXML) {
noOfResults = parser.countXML(dataTable);
} else {
noOfResults = parser.countJSON(dataTable);
}
}
return noOfResults;
},
/**
* Converts "raw" query results into Google JSON, using
* sgvizler.parser.
* @method getGoogleJSON
* @private
* @param {Object} data Query result set
* @return {JSON} JSON edable by google.visualization.DataTable
* @since 0.5
**/
getGoogleJSON = function (data) {
var gJSON = {};
if (getResultRowCount(data)) {
if (endpointOutputFormat() === qfXML) {
gJSON = parser.convertXML(data);
} else {
gJSON = parser.convertJSON(data);
}
}
return gJSON;
},
// TODO: add different listeners. onQuery, onResults, onDraw?
/**
* Add a function which is to be fired when the
* listener named `name` is fired.
*
* See `fireListener`
*
* @method addListener
* @private
* @param {String} name The name of the listener.
* @param {Function} func The function to fire.
* @example
* addListener("ready", function () { console.log("Ready!") });
* @since 0.6.0
**/
addListener = function (name, func) {
if (typeof func === 'function') { // accept only functions.
listeners[name] = listeners[name] || [];
listeners[name].push(func);
} else {
throw new TypeError();
}
},
/**
* Fires (runs, executes) all functions registered
* on the listener `name`.
*
* See `addListener`.
*
* @method fireListener
* @private
* @param {String} name The name of the listener.
* @since 0.6.0
**/
fireListener = function (name) {
if (listeners[name]) {
while (listeners[name].length) {
(listeners[name].pop())(); // run function.
}
}
},
/**
* Sends query to endpoint using AJAX. "Low level" method,
* consider using `saveQueryResults()`.
* @method sendQuery
* @private
* @async
* @return {jQuery.Promise} A Promise containing the query results.
* @since 0.5
**/
// TODO .fail, .progress: logging.
sendQuery = function () {
var promise, // query promise.
myEndpointOutput = endpointOutputFormat();
insertFrom();
if (myEndpointOutput !== qfJSONP &&
window.XDomainRequest) {
// special query function for IE. Hiding variables in inner function.
// TODO See: https://gist.github.com/1114981 for inspiration.
promise = (
function () {
/*global XDomainRequest */
var qx = $.Deferred(),
xdr = new XDomainRequest(),
url = endpointURL() +
"?query=" + getEncodedQuery() +
"&output=" + myEndpointOutput;
xdr.open("GET", url);
xdr.onload = function () {
var data;
if (myEndpointOutput === qfXML) {
data = $.parseXML(xdr.responseText);
} else {
data = $.parseJSON(xdr.responseText);
}
qx.resolve(data);
};
xdr.send();
return qx.promise();
}()
);
} else {
promise = $.ajax({
url: endpointURL(),
data: {
query: prefixesSPARQL() + query(),
output: (myEndpointOutput === qfJSONP) ? qfJSON : myEndpointOutput
},
dataType: myEndpointOutput
});
}
return promise;
},
/**
* Saves the query result set in the private property
* `results`. Works like a wrapper for sendQuery().
*
* See also saveDataTable().
*
* @TODO: also put the results in the promise object---and
* how to get them out?
*
* @method saveQueryResults.
* @private
* @async
* @return {jQuery.Promise} A Promise which resolves when
* the results are saved.
* @since 0.5
**/
saveQueryResults = function () {
var qr;
if (queryResult !== undefined) {
qr = queryResult;
} else {
qr = sendQuery();
qr.fail(
function (xhr, textStatus, thrownError) {
logger.log("Error: A '" + textStatus + "' occurred in Query.saveQueryResults()");
fireListener('onFail');
}
);
// add callback to save query results in object.
qr.done(
function (data) {
queryResult = data;
fireListener('onDone');
}
);
}
return qr;
},
/**
* Converts the the query result set into a
* google.visualization.DataTable, and if specified,
* applies datatable preprocessing function, and saves
* the datatable in the private property
* `dataTable`.
*
* @TODO: also put the results in the promise object---and
* how to get them out?
*
* @method saveDataTable
* @private
* @async
* @return {jQuery.Promise} A Promise which resolves when
* the datatable is saved.
* @since 0.5
**/
saveDataTable = function () {
/*global google */
var qdt, // query data table.
myDatatableFunction = datatableFunction();
if (dataTable) { // dataTable already computed.
qdt = dataTable;
} else {
qdt =
$.when(
saveQueryResults(),
loadDependencies(fDataTable),
// Get possible preprocess function.
(function () {
var loader = {};
if (myDatatableFunction) {
loader = loadDependencies(myDatatableFunction);
}
return loader;
}())
)
//TODO .fail(function () {})
.done(
function () {
dataTable = new google.visualization.DataTable(getGoogleJSON(queryResult));
if (myDatatableFunction) {
var func = util.getObjectByPath(myDatatableFunction);
dataTable = func(dataTable);
}
}
);
// TODO .fail, .progress: logging.
}
return qdt;
},
/**
* Draws the result of the query in a given container.
* @method draw
* @public
* @param {String} containerId The elementId of the
* container to draw the result of the query.
* @since 0.5
**/
draw = function (containerId) {
/*global google */
// Get query results and necessary charting functions in parallel,
// then draw chart in container.
var myChart = chartFunction();
$.when(saveDataTable(),
loadDependencies(myChart))
.then(
function () {
try {
// chart is loaded by loadDependencies.
var Func = util.getObjectByPath(myChart),
chartFunc = new Func(document.getElementById(containerId)),
ready = function () {
logger.log(myChart + " for " + containerId + " is ready.");
fireListener('onDraw');
};
// log when chart is loaded.
if (util.startsWith(myChart, moduleGooVis)) {
google.visualization.events.addListener(chartFunc, 'ready', ready);
} else if (chartFunc.addListener) {
chartFunc.addListener('ready', ready);
}
// dataTable is set by saveDataTable.
chartFunc.draw(dataTable, chartOptions);
} catch (x) {
// TODO: better error reporting, what went wrong?
logger.log(myChart + " -- " + x);
}
}
);
};
/////////////////////////////////////////////////////////
// Initialize things.
// Load default values, and overwrite them with values given
// in constructer parameters.
queryOptions = $.extend(defaults.getQueryOptions(),
queryOpt);
chartOptions = $.extend(defaults.getChartOptions(),
defaults.getChartSpecificOptions(chartFunction()),
chartOpt);
// Safeguard constructor.
if (!(this instanceof S.Query)) {
throw new Error("Constructor 'Query' called as a function. Use 'new'.");
}
////////////////////////////////////////////////////////
// PUBLICs
return {
//// attributes
noOfResults: noOfResults,
//// functions
draw: draw,
getEncodedQuery: getEncodedQuery,
// listeners
onFail: function (func) {
addListener('onFail', func);
},
onDone: function (func) {
addListener('onDone', func);
},
onDraw: function (func) {
addListener('onDraw', func);
},
/**
* @method getDataTable
* @public
* @param {Function} success
* @param {Function} fail
* @async
* @beta
*/
getDataTable: function (success, fail) {
$.when(saveDataTable())
.then(
function () {
var data = dataTable.clone();
success(data);
},
function () {
var data = dataTable.clone();
fail(data);
}
);
},
// TODO
/*getQueryResults : function (success, fail) {
$.when(saveQueryResults()).then(success(queryResult), fail);
},
getGoogleJSON: function (success, fail) {
getQueryResults(
function (queryResult) {
success(getGoogleJSON(queryResult));
},
fail
);
},*/
//// FROM
addFrom: addFrom,
clearFroms: clearFroms,
//// Getters/setters. Cascade pattern.
query: query,
endpointURL: endpointURL,
endpointOutputFormat: endpointOutputFormat,
endpointResultsURLPart: endpointResultsURLPart,
validatorURL: validatorURL,
loglevel: loglevel,
logContainer: logContainer,
datatableFunction: datatableFunction,
chartFunction: chartFunction,
chartHeight: chartHeight,
chartWidth: chartWidth
};
};
