OpenLink HTML5 WebDB-to-XMLA Bridge

The OpenLink HTML5 WebDB-to-XMLA Bridge is a Web browser extension that enables the development of database-driven HTML5 (Javascript) applications, without binding to specific back-end database engines for data storage and access.

XMLA is an HTTP based protocol for performing data access against multi-dimensional (OLAP and ROLAP) and tabular (Relational Databases) data sources.

This extension only deals with the tabular data sources that are directly accessible via XMLA or via ODBC/JDBC bridges.

Why use this bridge?

Initially, the WebDB API component of HTML5 confined data access and storage to SQLite. A bridge to ODBC extends the functionality of the WebDB API to any ODBC- (or JDBC-, via additional ODBC-to-JDBC bridges) -accessible database. Such RDBMS engines include OpenLink Virtuoso, Oracle, Microsoft SQL Server, IBM DB2, IBM Informix, Sybase, Ingres, Progress, MySQL, PostgreSQL, Firebird, and many more.

It is important to note, each RDBMS engine has its own features and limitations as an XMLA-accessible Database. OpenLink Virtuoso brings several additional benefits:

• Virtual/Federated RDBMS access (Commercial Edition only) -- A single XMLA connection to Virtuoso enables access to, and distributed joins across, all ODBC- or JDBC-accessible data sources.
  
• Graph Database (NoSQL, Triple-store, Quad-store) access -- A single XMLA connection to Virtuoso enables SPARQL access to local and/or remote SPARQL-compliant Graph-model-based DBMS engines via SPASQL (SQL and SPARQL hybrid query language).
  
• Extra security -- Fine-grained policy-based security leverages the WebID protocol across XMLA connections.

Installing the bridge

Installation Requirements and Prerequisites

To use the HTML5 WebDB-to-XMLA Bridge browser extension with Safari or Opera, you will need to first install an OS-specific (currently available for Linux, Windows, and Mac OS X) WebDB-to-XMLA Bridge Internet Plug-in. Once the plug-in is in place, you then install the actual HTML5 WebDB-to-XMLA Bridge extension(s) for your browser(s) of choice.

Note: If it is only intended to utilise synchronous API calls with OpenLink HTML5 WebDB-to-XMLA Bridge i.e. operate in Lite Mode, then the OS specific plugin installers below do not need to be installed as they are only required when asynchronous API calls are being made. In which case just the browser specific HTML5 WebDB-to-XMLA Bridge extension need be installed.

Windows Prerequisite: WebDB-to-XMLA Bridge Internet Plug-in

1. Download the Setup_HTML5_WebDb2XMLA_Plugin.exe installer.
   
2. Double click on the Setup_HTML5_WebDb2XMLA_Plugin.exe file to start the installer.
   
   
   
   
   
   
3. Select Next from the installer Welcome dialog to continue the installation
   
   
   
   
   
   
4. Select the destination location for the installation and click Next
   
   
   
   
   
   
5. Click the Install to install the components
   
   
   
   
   
   
6. Installation is complete
   
   
   
   
   

Mac OS X Prerequisite: WebDB-to-XMLA Bridge Internet Plug-in

• Download the HTML5_WebDB2XMLA_NPAPI_Plugin.dmg installer.
  
• Double click on the HTML5_WebDB2XMLA_NPAPI_Plugin.dmg file to start the installer.
  
  
  
  
  
  
• Double click on the HTML5 WebDB-to-XMLA (Bridge) NPAPI Plugin.mpkg package
  
  
  
  
  
  
• Select continue from the installer Welcome dialog to continue the installation
  
  
  
  
  
  
• Click install to begin installation
  
  
  
  
  
  
• Enter password to authorize installation
  
  
  
  
  
  
• Installation is complete
  
  
  
  
  

Linux Prerequisite: WebDB-to-XMLA Bridge Internet Plug-in

1. Download the Setup_HTML5_WebDb2XMLA_Plugin.sh script.
   
2. Run the Setup_HTML5_WebDb2XMLA_Plugin.sh script --
   
   

   
   % sh Setup_HTML5_WebDb2XMLA_Plugin.sh 
   Creating directory bin
   Verifying archive integrity... All good.
   Uncompressing OpenLink HTML5 WebDb-to-XMLA (Bridge) Plugin ver:1.0.8...
   
   Started installation on : opllinux5  /home/virtuoso/bin
   
   Copying 'OpenLink HTML5 WebDB-to-XMLA (Bridge) Plugin ver:1.0.8' to /usr/lib/mozilla/plugins/
   End of installation
   %
   

   
   
3. Change directory to the created "bin" directory and run the install.sh script to install the "OpenLink HTML5 WebDB-to-XMLA (Bridge) Plugin"
   
   

   
   % cd bin
   % ls -l
   total 92
   -rwxr-xr-x 1 root root   473 Jan 10 10:11 install.sh
   -rwxrwxr-x 1 root root 73772 Jan 10 10:17 libnpxmla.so
   % sh install.sh
   
   Started installation on : opllinux5  /home/virtuoso/bin
   
   Copying 'OpenLink HTML5 WebDB-to-XMLA (Bridge) Plugin ver:1.0.8' to /usr/lib/mozilla/plugins/
   End of installation
   %
   

   
   
   

Install the HTML5 WebDB-to-XMLA Bridge Extension

Download and install the HTML5 WebDB-to-XMLA Bridge Extension for your preferred Browser(s):

• Safari
  
• FireFox
  
• Google Chrome
  
• Internet Explorer 9
  
• Opera

How do I use the Bridge?

Once the XMLA Provider for UDA or Virtuoso has been installed and configured, you can perform any of the following tasks:

• Use our HTML5+WebDB based XMLA Data Explorer against a variety of ODBC accessible data source(s) configured on your XMLA Server.
  
• Use our HTML5+WebDB XMLA Sample Application to automatically test Synchronous and/or Asynchronous WebDB API calls.
  
• Use a third-party HTML5+WebDB compliant application -- or develop your own.

How do I obtain XMLA Providers?

• OpenLink Virtuoso XMLA Provider -- http://docs.openlinksw.com/virtuoso/xmlxmla.html
  
• OpenLink UDA XMLA Provider -- http://wikis.openlinksw.com/dataspace/owiki/wiki/UdaWikiWeb/InstallConfigXMLAProviders

Note for Google Chrome and Safari users: For XMLA Providers that do not support cross domain scripting, the XMLA provider and the XMLA client application (e.g., XMLAsample1.html), must be hosted on the same machine (i.e., the same web server). Currently, neither the Virtuoso XMLA Provider nor the UDA XMLA Provider supports cross domain scripting.

Connect Strings

The HTML5 WebDB-to-XMLA Bridge supports connect strings for the following XMLA Providers:

UDA Multi-Tier

• URL: http:<hostname>[:<portno>]/XMLA
  
• DSN: <ODBC DSN>
  
• UID: <username>
  
• PWD: <password>

UDA Single-Tier

• URL: http:<hostname>[:<portno>]/Xmla/Service.asmx
  
• DSN: <XMLA Provider DSN>
  
• UID: <username>
  
• PWD: <password>

Virtuoso

• URL: http:<hostname>[:<portno>]/XMLA
  
• DSN: leave blank
  
• UID: <username>
  
• PWD: <password>

Note: The Virtuoso XMLA Provider currently only supports read-only connections, hence the Readonly Test Sync Database calls and Readonly Test Async Database calls tests have to be used when running the XMLAsample1.html test page. Thus before executing Virtuoso readonly tests, the following tables need to be created and data inserted:

create table test (id integer primery key identity, string varchar(20), number double precision, nuller varchar(20), blober long varbinary);
insert into test(string,number,nuller,blober) values('str0',11111.22, NULL,0x01020304050607);
insert into test(string,number,nuller,blober) values('str1',22222.33, NULL,0x02030405060808);

Virtuoso versions 6.1.3 and later will support DML (write operations), although by default XMLA connections will be read-only as a security precaution. Running the following command as the dba user will enable write operations --

registry_set ('XMLA-DML','1');

Database Catalog Calls

New General Methods

• To get a resultSet listing DSN names
  
  

  
  nsIXMLAResultSet
    XMLAUtils.discoverDataSources
      ( IN  DOMString  url
      );
  

  
  
• To get a resultSet listing column names
  
  

  
  DOMString
    nsIXMLAResultSetMetaData.getColumnName
      ( IN  unsigned short  aIndex
      );
  

  
  

DB catalog calls

For nsIXMLATransactionSync (synchronous transaction execution)

nsIXMLAResultSet 
  getCatalogs();

nsIXMLAResultSet
  getTables
    ( IN  DOMString  catalog   ,
      IN  DOMString  schema    ,
      IN  DOMString  table     ,
      IN  DOMString  tableType
    );

nsIXMLAResultSet
  getColumns
    ( IN  DOMString  catalog ,
      IN  DOMString  schema  , 
      IN  DOMString  table   , 
      IN  DOMString  column
    );

nsIXMLAResultSet
  getPrimaryKeys
    ( IN  DOMString  catalog , 
      IN  DOMString  schema  , 
      IN  DOMString  table
    );

nsIXMLAResultSet
  getForeignKeys
    ( IN  DOMString  pcatalog , 
      IN  DOMString  pschema  , 
      IN  DOMString  ptable   ,
      IN  DOMString  fcatalog , 
      IN  DOMString  fschema  , 
      IN  DOMString  ftable
    );

nsIXMLAResultSet
  getTypeInfo
    ( IN  short  dataType
    );

nsIXMLAResultSet
  getProcedures
    ( IN  DOMString  catalog   , 
      IN  DOMString  schema    , 
      IN  DOMString  procedure
    );

nsIXMLAResultSet
  getProcedureColumns
    ( IN  DOMString  catalog   , 
      IN  DOMString  schema    , 
      IN  DOMString  procedure , 
      IN  DOMString  column
    );

For nsIXMLATransaction (asynchronous transaction execution)

void 
  getCatalogs
    (
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void 
  getTables
    ( 
                  IN  DOMString                      catalog       ,
                  IN  DOMString                      schema        ,
                  IN  DOMString                      table         ,
                  IN  DOMString                      tableType     ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void 
  getColumns
    ( 
                  IN  DOMString                      catalog       ,
                  IN  DOMString                      schema        ,
                  IN  DOMString                      table         ,
                  IN  DOMString                      column        ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void getPrimaryKeys(
                  IN  DOMString                      catalog       ,
                  IN  DOMString                      schema        ,
                  IN  DOMString                      table         ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void getForeignKeys(
                  IN  DOMString                      pcatalog      ,
                  IN  DOMString                      pschema       ,
                  IN  DOMString                      ptable        ,
                  IN  DOMString                      fcatalog      ,
                  IN  DOMString                      fschema       ,
                  IN  DOMString                      ftable        ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void 
  getTypeInfo
    (
                  IN  short                          dataType      ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void 
  getProcedures
    (
                  IN  DOMString                      catalog       ,
                  IN  DOMString                      schema        ,
                  IN  DOMString                      procedure     ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

void 
  getProcedureColumns
    ( 
                  IN  DOMString                      catalog       ,
                  IN  DOMString                      schema        ,
                  IN  DOMString                      procedure     ,
                  IN  DOMString                      column        ,
      [optional]  IN  nsIXMLAStatementCallback       callback      ,
      [optional]  IN  nsIXMLAStatementErrorCallback  errorCallback
    );

Lite Mode

The OpenLink HTML5WebDB-to-XMLA Bridge includes a Lite Mode that only utilizes synchronous calls. This aspect of the API enables the implementation of an XMLA Explorer application that works with any browser without requiring pre installation of the WebDB-to-XMLA Bridge plugin.

The files webdb_xmla_min.js and xmla_min.js showcase how the XMLA Explorer has been implemented using the "XMLALite" APIs. Specifically, this is achieved by invoking methods of the form:

  XMLALite.discoverDataSources(...)
  XMLALite.openXMLADatabaseSync(...)

Whereas for Full Mode the XMLA entry point is called "XMLAUtils", invoked with methods of the form:

  XMLAUtils.discoverDataSources(...)
  XMLAUtils.openXMLADatabaseSync(...)

Synchronous methods supported by the XMLA Lite Mode

interface nsIWorkerXMLADatabase : nsISupports {
 nsIXMLADatabaseSync openXMLADatabaseSync(in DOMString url,
 	in DOMString dsn,
 	in DOMString cat,
 	in DOMString uid,
 	in DOMString pwd,
 	in DOMString version,
 	[optional] in nsIXMLADatabaseCallback creationCallback);

 nsIXMLAResultSet discoverDataSources(in DOMString url);
};

interface nsIXMLADatabaseSync : nsISupports {
 void transaction(in nsIXMLATransactionSyncCallback callback);
 void readTransaction(in nsIXMLATransactionSyncCallback callback);
 readonly attribute DOMString version;
 void changeVersion(in DOMString oldVersion, in DOMString newVersion,
 	[optional] in nsIXMLATransactionSyncCallback callback);
};


interface nsIXMLATransactionSync : nsISupports {
 nsIXMLAResultSet executeSql(in DOMString sqlStatement,
 	[optional] in nsIVariant arguments);
 nsIXMLAResultSet getCatalogs();
 nsIXMLAResultSet getTables(in DOMString catalog, in DOMString schema,
 		in DOMString table, in DOMString tableType);
 nsIXMLAResultSet getColumns(in DOMString catalog, in DOMString schema,
 		in DOMString table, in DOMString column);
 nsIXMLAResultSet getPrimaryKeys(in DOMString catalog, in DOMString schema,
 		in DOMString table);
 nsIXMLAResultSet getForeignKeys(in DOMString pcatalog, in DOMString pschema,
 		in DOMString ptable, in DOMString fcatalog, in DOMString fschema,
 		in DOMString ftable);
 nsIXMLAResultSet getTypeInfo(in short dataType);
 nsIXMLAResultSet getProcedures(in DOMString catalog, in DOMString schema,
 		in DOMString procedure);
 nsIXMLAResultSet getProcedureColumns(in DOMString catalog, in DOMString schema,
 		in DOMString procedure, in DOMString column);
};


interface nsIXMLATransactionSyncCallback : nsISupports {
 void handleEvent(in nsIXMLATransactionSync transaction);
};


interface nsIXMLAResultSet : nsISupports {
 readonly attribute long insertId;
 readonly attribute long rowsAffected;
 readonly attribute nsIXMLAResultSetRowList rows;
 readonly attribute nsIXMLAResultSetMetaData metaData;
};

interface nsIXMLAResultSetMetaData : nsISupports {
 readonly attribute unsigned short columnCount;
 DOMString getColumnType(in unsigned short aIndex);
 boolean isNullable(in unsigned short aIndex);
 DOMString getColumnName(in unsigned short aIndex);
};


interface nsIXMLAResultSetRowList : nsISupports {
 readonly attribute unsigned long length;
 nsIVariant item(in unsigned long index);
};


interface nsIXMLAException : nsISupports {
 readonly attribute long code;
 readonly attribute DOMString message;
 readonly attribute DOMString state;
};

Related Links

• HTML5 WebDB-to-ODBC Bridge
  
• Web SQL Database API Spec
  
• OpenLink Virtuoso Universal Server Home Page
  
• OpenLink Universal Data Access Home Page
  
• Platform-Independent iODBC Project Home Page
  
• WebID
  
• WebID FAQ