jsquery

AJAX Javascript Resultset, http client and server code generator.

Version: 1.0 - Copyright 2005,  Bensoft Inc.

Summary

An implementation of an AJAX javascript data generation server, http client, and client result set

Uses a javascript http client to dynamically map the results of data requests from a Java application server to a web browser HTML form without requiring refresh or page submit (similar to Google Suggest). Server side data can be SQL via JDBC, an object relational mapping using a tool such as Hibernate, returned from a server connecting a group of peers or pipelined from another source like a SOAP server.

In other words,  jsquery allows the pages in your web application to dynamically get new information from the a server application without requiring a page refresh.  For a quick functional example of why you would want to do this,  see the sql zip code example .

Overview:

jsquery is divided into three parts:

1. Javascript http client

   {WebRoot}/js/jsquery_httpclient.js - A javascript http client that calls a server side query and evaluates the results into a jsquery_resultset

2. Java server side generator in src/com/bensoft/jsquery

   JSGenerator.java - Generates a javascript representation of a 2D data matrix into a jsquery_resultset instance

   ResultSet2JS.java - Converts a Java JDBC ResultSet into javascript using JSGenerator

   Types.java - Defines the simplified types for jsquery_resultset.js which include Number, String, Date, and Boolean.

3. Javascript ResultSet

   {WebRoot}/js/jsquery_resultset.js - A javascript implementation of the JDBC ResultSet that reads from a query result embedded into a series of javascript arrays that are generated by the server.

Links

For API readers:

1. Client

   see docs/js/api.html for the client side documentation.

2. Server

   see docs/api/index.html for the server side documentation.

3. Then see the examples

   To demo static client side JS you can use:

   1. test_resultset.html - examples of using the resultset from a static source.
   2. test_httpdclient.html - examples of calling server and parsing result into a static source.

   For easiest understanding of client/server, review the examples in this order

   3. hello  -  most basic skeletal example
   4. demo - demonstrates sending single row of all data types

   For JDBC/SQL users

   5. sql   (you'll need to config for your db, and load a SQL definition)

   For OR Mapping guidance

   6. manual

Dependencies

1. Apache commons-lang-2.1 used to Escape data into a javascript array.
2. Optional: JDBC ResultSet used to map data to the client side

Installing and running examples

Definitions

app server - Something that runs Java Servlets and JSP pages.

web root - root path of an application deployed on an app server

1. Place contents of WebRoot/js into the app server web root 'js' folder.
   
   
2. Place lib/jsquery.jar into the app server web root WEB-INF/lib directory.
   
   
3. To run the ' examples ', copy them directories to an app server web root 'examples'
   
   
4. To run examples/sql , additionally you will need to:
   
   
   1. create a database (tested with MySQL but any database with a JDBC driver should work)
      
      
   2. load the zip.sql script into the database
      
      
   3. edit getzip.jsp and set JDBC parameters for your database of choice (just four lines together)
      
      
   4. make sure your JDBC driver jar file is in WEB-INF/lib or your app servers shared lib directory.
      
      

About the Examples

1. examples/js - Can run on client without an application server

   Static test of javascript libraries

   Client:

   1. test_resultset.html - Example result set test using static data.js
   2. test_httpclient.html - Example http client call and display using static data.js

   Server (static):

   3. data.js - static server side data image
   
   
2. examples/hello - REQUIRES app server deployment

   Minimal Hello World example

   Client:

   1. hello_client.html - Dynamic Hello world client

   Server:

   2. hello_server.jsp - Dynamic Hello world server
   
   
3. examples/demo - REQUIRES app server deployment.

   Demo shows handling of all 4 data types Number,String,Date, and Boolean

   Client:

   1. demo_client.html - Demo client side process all four data types.

   Server:

   2. demo_server.jsp - Demo server side send all four data types.
   
   
4. examples/manual - REQUIRES app server deployment

   Manual server side loading of data.

   Client:

   1. manual_client.jsp - Client that calls server to get data and displays it.

   Server:

   2. manual_server.jsp - Server side generator (non-JDBC manually built)

   Client & Server:

   3. inline_client_server.jsp ( source ) - In-line server side generate and client side iterate.
   
   
5. examples/sql - REQUIRES app server deployment (tomcat will do)

   Example of calling jsquery using JDBC data source (Load zip.sql into your favorite DB and modify getzip.jsp with JDBC driver and access info.

   Client

   1. zipform.jsp ( source )- Client side form that makes zip code queries

   Server

   2. zip.sql - Zip code test data
   3. getzip.jsp - Server side zip result provider, uses JDBC auto-mapping.
   
   

Using your favorite datasource with jsquery

In a nutshell, your data translator should call JSGenerator methods in the following order:

1. Send the metadata (data definition):
   
   
   • writeResultSet - client side declaration of jsqueryResultSet object.
     
   • writeTableName - set the name of the return table
     
   • addColumnDef - LOOP: add a column definition (call for all columns).
     
   • writeColumnNames - write the column names Array to the client javascript.
     
   • writeColumnTypes - write the column types Array to the client javascript.
     
2. Or use the quick metadata method:
   
   
   • addColumnDef - LOOP: for each column defined
     
   • writeMetaData - in place of all writeXXX methods above
     
3. Then iterate through your 2D data:

   LOOP: for each row of data

   • addColumnValue - LOOP: for each column definition above
     
   • writeRow - at end of columns
     
4. when done call:
   
   
   • writeEnding = Stub for stuff to do afterwards.
     

How it works - Step by step:

1. A javascript client function uses the http client to make a request from the server. The request can be encapsulated into a JSP or a Servlet. This is done without any page refresh or submission. A function is defined to call when the data is ready, and the javascript function returns immediately.
   
2. The JSP/Servlet reads the request parameters from the URL (GET refs) and generates data. The source can be anything the server has access to such as a SQL database, Object Relational Map, SOAP service, etc...
   
3. The JSP/Servlet then returns the data as a set of names and types (metadata) and a 2-dimensional data grid (rows of columns) using javascript Array objects. This data is encapsulated into a block of javascript (1.3. spec) so that the client can easily parse the result using the eval() function. The server side 'streams' the resulting javascript to minimize server memory load.
   
4. When the transfer is complete, the http client automatically runs a user defined javascript function that evaluates the result from the server and processes it using a JDBC ResultSet style interface. The client receives the entire result set at once requiring enough memory on the client to hold the entire data set (in other words, don't send 10,000 rows of a large data set to the client!)

TODO

• Server Side Application Layer Query Security Layer.  I am thinking about using a library like
  
• A JS/DHTML 'history' dropdown could be incorporated to provide a server-side suggestion interface.
  
• Add user interface component to dynamically populate and set SELECT/OPTION elements.
  
• Integrate with a dynamic list interface like http://javascriptools.sourceforge.net/
  
• I decided not to tackle sending the data to the server via HTTP POST. Looks like it's not supported well by some browsers and more trouble that it's worth. Let me know if this is a problem for you and I'll look into supporting it.
  
• A chat application using zero-disk and an application context would be cool.
  
• An app context multi-user game of some sort.

History:

I first experimented with the idea of generated code for data encapsulation back in the mid 90's when I was writing perl based content systems for the web  with Data::Dumper.pm  and eval()

In the late 90's I built a client/server fantasy sports engine for juniornet.com implementing a server-side mod_perl engine that generated a client side lingo code representation of an Oracle query for a shockwave ( director ) interface.

Recently, I noticed several organizations using the XMLHttpRequest API in combination with the same techniques. evaluating server prepared javascript code on the browser client.

I needed this for various projects so I wrote jsquery as a Javascript <.> Java implementation and documented it to help explain the concept to others.

Advantages of this script encapsulation technique:

1. Easy to develop, you only need to write one side of the data protocol.
2. Fast! using an eval() type function is usually much faster then an interpreted script-based parser.
3. Lower memory footprint. Lightweight components can be used with native data types generated by the protocol side you did write :)

License

This software is licensed under the terms of the GNU PUBLIC LICENSE .

If you wish to include jsquery in your commercial product, or if you require a different licensing arrangement, please contact  us at sales@bensoft.com .

Special Thanks to:

Paul Zepernick - Fixing bugs in javascript resultset and example getzip.jsp

Author