return to index
xsdb project page with download links
xFeedMe xsdb resources

xsdbXML javascript implementation notes

The javascript xsdbXML implementation allows programs to use the xsdbXML framework in javascript enhanced web pages and applications. The javascript xsdb implementation has been tested using the MSIE 6.0 and FireFox 1.5 browsers under MS Windows XP. Please report problems under environments which are expected to support a modern version of javascript (1.4 or better).

The entire system is packaged as a single file so that it may be easily included in web pages: xsdbjs/xsdball.js. The "xsdball" file is constructed by concatenating most of the other javascript files in the directory in the right order so the symbols resolve correctly.

Simple demonstrations of the xsdb system may evaluate xsdb queries directly encoded on the HTML web page. A trivial example of such an evaluation is provided in xsdbjs/test1.html which has the following content:

<h1>Test of javascript</h1>

<script src="xsdball.js">

<script language="JavaScript">

queryString('<calc at="x" expr="4+5"/>')

In this example the queryString function evaluates a simple xsdb assertion and writes the result to the page. This example may be run locally from the filesystem without the cooperation of a web server (but if you use MSIE to view the page you must "allow blocked content" to enable local javascript). The page generated should look something like this

Test of javascript

</i at="x">9</i>
There are a number of other string evaluation examples in the xsjdbjs/htmltests/ subdirectory.

More interesting uses of the xsdb system require access to a web server because interesting applications usually require access to data from files in addition to data from javascript strings encoded directly in the page. All file contents retrieved by xsdb must be delivered by a web server because (for portability and security reasons) xsdb only supports the HTTP protocol for accessing files (in particular the FILE protocol is not supported at this time).

NOTE: As a security feature javascript does not allow a javascript program to load a file from a domain other than the domain provided the javascript component. For this reason it is not possible to use javascript directly to query xsdb data sets that reside on different domains. For example the examples/SupplierParts/remote_parts_query.xsdb does not work under the javascript implementation because of this limitation.

The demos

The xsdbjs directory includes a number of demo pages. These pages must be installed in a web server directory before they will work properly.

Setting up the demos with a web server

To get the demo pages running you must have the ability to install subdirectories below a web server html publication root. In my case I have a local web server running on my workstation. To get the demos working I:

You may prefer to put the directories somewhere else, but they must be under the same parent directory to work properly. If you put them further down, however, the locations may look more like http://localhost/some/other/location/xsdbjs/runtests.html (for example).

The javascript application programmers interface

The primary interface to the framework from an external javascript program is mediated by instances of the Query class.

Create a Query object from a query text string using the constructor

Q = StringQuery(text)
// or
Q = StringQuery(text, contextLocation);
// or 
Q = StringQuery(text, contextLocation, verbose);
Where text is the body of the query, contextLocation is a directory path used to resolve relative file system references and verbose boolean flag which when set true causes the framework to generate debugging output. If omitted the contextLocation defaults to the document.location.href and the verbose flag defaults to false.

A program may extract the result of a query as an XML string, an ArrayList of ArrayLists or as an ArrayList of Hashtables as explained below.

ArrayLists and Hashtables

For (my) convenience the xsdb javascript implementation uses emulations of the java Hashtable and ArrayList container classes. An ArrayList List is a sequence object implemented using an internal javascript Array object List.L. Most javascript programmers may prefer to use the array List.L directly rather than learn more about ArrayLists. A Hashtable H is a mapping object implemented using javascript associative arrays. It provides the following methods:

The query results return ArrayLists and Hashtables as explained below.

Note: some future version of the javascript implementation should limit the use of the ArrayList and Hashtable containers as much as possible (they are primarily an artifact of porting expediency) but the Query interfaces should be maintained for backwards compatibility.

Query results

The result of a normal xsdb evaluation is a sequence of mappings from names to values. The Query.Dictionaries(...) method presents the result as a sequence of Hashtables where the keys for the table are the names and the values for the table are the values associated with each name. The Query.Tuples(...) method presents the result as a sequence of ArrayLists containing the values associated with the names. If the order of the names is specified in the query the values are provided in the order requested, otherwise the values are provided sorted alphabetically by the associated name. The Query.StringResult(...) method presents the result as an xml string similar to those generated by the query and test applications.

The signatures of these methods are

arrayListResult = Q.Dictionaries(strict) 
arrayListResult = Q.Tuples(strict)
strintgResult = Q.StringResult(strict) 
In each case if the strict parameter is set true (the default) will trigger an exception if the result of the query cannot be converted to a purely positive form. The strict parameter may be omitted, in which case it defaults to false.

The included APIDemo.html page provides a very simple demonstration of each of these methods. The main method for the application is listed below
<HTML><h1>Demonstration of the xsdb javascript API</h1>

<script src="xsdball.js">

<script language="JavaScript">

// Initialize a query from a String literal
var  querytext = (
"<query names=\"salutation age\" sort=\"age\">\n"+
"	<and>\n"+
"		<s at=\"salutation\">hello kind world</s> <i at=\"age\">0</i>\n"+
"	</and>\n"+
"	<and>\n"+
"		<s at=\"salutation\">goodbye cruel world</s> <i at=\"age\">99</i>\n"+
"	</and>\n"+
document.write("query text = \n"+quote(querytext));
var Q = StringQuery(querytext)

document.write("\n\n String result is\n"+quote(Q.StringResult(false)));

document.write("\n\n hash table result");
var Hashes = Q.Dictionaries(false);
var ArrayOfHashtables = Hashes.L;
for (var i=0; i<ArrayOfHashtables.length; i++) 
	var H = ArrayOfHashtables[i];
	var age = H.get("age");
	var salutation = H.get("salutation");
	document.write("\n   age="+age+"  salutation="+salutation);

document.write("\n\n array list result");
var tuples = Q.Tuples(false);
var ArrayOfArrayLists = tuples.L;
for (var i=0; i<ArrayOfArrayLists.length; i++) 
	var A = ArrayOfArrayLists[i];
	var arry = A.L;
	var age = arry[1];
	var salutation = arry[2];
	document.write("\n   age="+age+"  salutation="+salutation);

This javascript enhanced html page generates something like the following:

Demonstration of the xsdb javascript API

query text = 
<query names="salutation age" sort="age">
		<s at="salutation">hello kind world</s> <i at="age">0</i>
		<s at="salutation">goodbye cruel world</s> <i at="age">99</i>

 String result is
      <s at="salutation">hello kind world</s>
      <i at="age">0</i>
      <s at="salutation">goodbye cruel world</s>
      <i at="age">99</i>

 hash table result
   age=0  salutation=hello kind world
   age=99  salutation=goodbye cruel world

 array list result
  age=0  salutation=undefined
  age=99  salutation=undefined

Arithmetic expressions

The arithmetic expressions used in the calc and cond predicates match the Python implementation except that certain arithmetic functions supported in Python are not yet supported in the javascript implementation. In particular the javascript implementation supports the following arithmetic functions within arithmetic expressions.
Signature Summary
int(x), float(x), str(x) Data type conversion.
round(x), floor(x), ceil(x)
abs(x), sqrt(x), log(x)
sin(x), cos(x), tan(x)
asin(x), acos(x), atan(x)
Standard floating point functions.
e(), pi() Function notation for floating point constants.
strip(s), upper(s), lower(s)
find(inString, pattern [, start [,end]])
string functions.
max(x.y), min(x.y)
count(x.y), avg(x.y), med(x.y)
Group aggregate operations.
These functions have the same semantics as in the Python implementation.
End of xsdbXML javascript implementation notes
return to index