Archive for August, 2008

Jaxer, E4X and Prototype

Monday, August 4th, 2008

The ECMAScript for XML standard a.k.a “E4X” is a cool addition to JavaScript that provides for native support of XML. E4X adds nifty features such as simplified XML traversal and XML literals to the language. E4X is supported in Mozilla and Adobe JavaScript implementations. The lack of support in IE hinders the widespread adoption of E4X. However, E4x is supported on Aptana Jaxer.

I’ve been using Jaxer for web development lately. Jaxer is a web application server which uses JavaScript on the server side. The server-side JavaScript implementation is based on Mozilla, and E4X is supported. So, if you’re using Jaxer, there is nothing holding you back from using E4X on the server side.

With this in mind, I’ve cooked up an example intended to whet your appetite for E4X. The source code is shown below. The example executes a query against a database and renders each returned row as a HTML table. I’m using E4X for two tasks: storing configuration data and filling in a HTML template.

Note how various scripts or functions are tagged with runat='server'. This is how Jaxer knows which scripts to process on the server and which not to. All of the scripts in this example run on the server. The execution of the scripts is started by the onserverload attribute of the body tag. This is the server-side equivalent to the onload attribute in the browser context.

For the configuration example, I stored SQL statements in an XML document. I needed a select query to execute against the database, and then of course I realized I needed some DDL to create the table and some more SQL to insert records. I decided to store all of my queries as E4X XML literals in JavaScript embedded in my HTML page. The embedded XML is seen only on the Jaxer Server, and not in the client browser. On lines 12-37 I used an XML literal to declare an XML document containing 3 SQL statements.

A couple of points to note. First I embedded this configuration into a HTML page. With the Jaxer server-side facilities for accessing the file system, one could store the XML in a file and share the configuration across HTML pages. Second, with a CDATA section (lines 27-29), I don’t have to worry about escaping my SQL to make valid XML.

IMHO, the coolest E4X feature is simplified DOM access. The code to pull out a particular SQL statement by id is:

var sqlToRun = sqlStatements.sql.(@id == 'select-persons-no-heavier-than');

After executing the select query, I render each row as a little HTML table. On line 50 I access each record via the Jaxer.DB.ResultSet API. I create a table for each record with an XML literal on lines 52-69. One nice feature of E4X is the ability to execute arbitrary JavaScript code within the XML literal. For example, line 67:

<td>{(dbRecord.weight_kg / 0.454).toFixed(2)}</td>

reads a JavaScript object property, divides by .45, renders the number with 2 decimal places, and then places that value in the td tag. Finally on line 74, I insert the table into the page’s DOM tree. The insert is done with Prototype’s Element.insert method which takes a string or DOM Node as an argument and inserts the content into the page’s DOM tree.

Don’t forget, that all of the scripts tags (for prototype.js as well) have a runat=”server” attribute, so all of this action happens on the Jaxer server before the page is render as text and sent to the client.

One interesting point is that I used Prototype on the server side. My usage was pretty modest here; I take it as a good sign that the server side JavaScript environment closely matches the JavaScript environment in a browser.

I’m pretty happy with this example code. I think the templating of HTML turned out to be very transparent and easy to understand code. Several factors contribute to clean code: XML literals avoid cluttering the code with quoted string and also allow value interpolation, and insertion of the XML strings into the DOM tree with Prototype. This is a nice illustration of the handy features that are available in the Jaxer server side programming environment.

 <html>
     <head>
   <title>Jaxer E4X Example</title>

     /*
    * All of the JavaScript is running on the server due to the
    * runat="server" attribute of the script tags
    */
     <script runat="server" src="lib/prototype/prototype.js"></script>
     <script runat="server">

   // An XML literal holding template SQL
     var sqlStatements =
       <sql-statements>
         <sql id='create-table'>
           create table if not exists person (
             id      integer,
             first_name  varchar(20),
             last_name   varchar(20),
             birth_date  datetime,
             weight_kg   decimal(5,2),
             height_m    decimal(5,2),
             constraint person_pk primary key(id)
           );
         </sql>
         <sql id='insert-person'>
           insert into person
             (id, first_name, last_name, birth_date, weight_kg, height_m)
           values
             (?, ?, ?, ?, ?, ?)
         </sql>
         <sql id='select-persons-no-heavier-than'>
           <![CDATA[
             select * from person where weight_kg <= ?
           ]]>
         </sql>
       </sql-statements>;

     // Called on server side page load.
     // Triggered by the onserverload attribute of the body tag
       function showPersonDetails() {

     // Find a SQL statement by name
         var sqlToRun = sqlStatements.sql.(@id == 'select-persons-no-heavier-than');

     // Execute the SQL with the Jaxer.DB API
         var resultSet = Jaxer.DB.execute(sqlToRun, 200);

     // For each record returned from the DB...
     resultSet.rows.forEach(function(dbRecord, index) {
       // Create some markup using a XML Literal and value interpolation
           var tbl =
           <table border='1'>
             <tr>
               <td colspan="2">Person Detail</td>
             </tr>
             <tr>
               <td>First name:</td>
               <td>{dbRecord.first_name}</td>
             </tr>
             <tr>
               <td>First name:</td>
               <td>{dbRecord.last_name}</td>
             </tr>
             <tr>
               <td>Weight in pounds:</td>
               <td>{(dbRecord.weight_kg / 0.454).toFixed(2)}</td>
             </tr>
           </table>;

           tbl += <br/>;

       // add the new markup to the page DOM
           $('person-details').insert(tbl.toXMLString());
     });
       }

     </script>
   </head>
   <body onserverload="showPersonDetails();">
       <div id='person-details'>
       </div>
   </body>
 </html>

Jaxer CRUD

Sunday, August 3rd, 2008

Aptana’s Jaxer is a Web Application platform that uses JavaScript on the server side. I’m starting to develop a real taste for the JavaScript language, so Jaxer is a nice place to try out new modes of JavaScript programming.

Server side programming for Web Applications typically involves a good bit of interaction with a database. As a Java developer, I typically use JDBC or an Object Relational Mapping (ORM) framework such as Hibernate for database interaction. If you look around, you’ll find JavaScript lacks such established API/Frameworks for DB interaction (though it looks like some JavaScript ORMs are being actively developed). At this point in time, things are pretty much DIY.

With this in mind, I’ve worked up some code example for CRUD operations using the Jaxer database API. This is a simple example, intended to help folks climb up the Jaxer learning curve. The complete source code for the example is at the bottom of this post.

The example reads and writes from elements on a HTML page and also a database table. In the example, there are HTML tables which describe a person, and likewise, I’ve created a table in the database that has the same attributes (with slightly different names, just to keep this real. The table DDL is in the example code). Here’s a screen shot of the example:

Jaxer CRUD Example screenshoot

The flow of the example is:

1) Read attributes from the first (from the top) HTML table and then create a corresponding record in the database.

2) Read the same attributes back from the database and then populate the next HTML table

3) Read attributes from the third HTML table and update the database

4) Delete the record from the database.

Line 108 also shows an interesting capability of Jaxer: The script block there is set to runat=”server-proxy”. This tells Jaxer to run these scripts at the server, but let them be callable from the browser. So when I click the CRUD button on the client, it calls runExample on line 14, which in turn calls the four CRUD functions which run at the server. I’m actually calling a function on the server directly from the client! Note too that this example uses blocking calls from the browser to the Jaxer server. It is very easy to change this code to the Jaxer asynchronous API, which is likely topic for my next post.

Without further ado – the code:

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
 <html>
   <head>
     <title>Jaxer CRUD</title>
     <script type="text/javascript" src="prototype.js"></script>

     /*
      *  Scripts that run in the client browser
      */
     <script runat='client'>
       //
       //  Run the example on button click
       //
       function runExample() {
         // server side method that creates a table if needed
         createTable();
         // Do the CRUD operations
         createPerson();
         readPerson();
         updatePerson();
         deletePerson();
       }

       // Create a person in the DB based on properties read from a HTML table
       function createPerson() {
         // pull properties from HTML table
         var p = objectFromTable('create-table');
         // write to DB via server proxy call
         createPerson_Server(p);
       }

       // Read a person from the DB and write to a HTML table
       function readPerson() {
         // read the person from the DB via a server proxy method
         var p = readPerson_Server(1);
         // populate the HTML table
         tableFromObject('read-table', p);
       }

       // Update a person in the DB based on properties read from an HTML table
       function updatePerson() {
         // read the person properties from an HTML table
         var p = objectFromTable('update-table');
         // update the DB via a server proxy call
         updatePerson_Server(p);
       }

       // Delete a person in the DB
       function deletePerson() {
         // Server call to delete in the DB
         deletePerson_Server(1);
       }

       //
       // Utility functions
       //

       // populate an object from values in a HTML table
       function objectFromTable(tableId) {
         var o = {};
         var propNames = $$('#' + tableId + ' th');
         var props = $$('#' + tableId + ' td');
         var propNum = 0;
         propNames.each(function(item) {
           o[item.innerHTML] = props[propNum++].innerHTML;
         });
         o.birthDate = dateFromStr(o.birthDate);
         return o;
       }

       // populate a HTML table from values in an object
       function tableFromObject(tableId, anObject) {
         anObject.birthDate = strFromDate(anObject.birthDate);
         var propNames = $$('#' + tableId + ' th');
         var props = $$('#' + tableId + ' td');
         var propNum = 0;
         propNames.each(function(item) {
           props[propNum++].innerHTML = anObject[item.innerHTML];
         });
       }

       // convert from string 'yyyy-mm-dd' to JS Date
       function dateFromStr(dateStr) {
         if(dateStr) {
           var dateParts = dateStr.split('-');
           var date = new Date();
           date.setFullYear(dateParts[0]);
           date.setMonth(dateParts[1] - 1);
           date.setDate(dateParts[2]);
         }
         return date;
       }

       // convert from JS Date to string 'yyyy-mm-dd'
       function strFromDate(aDate) {
         var str = '';
         if(aDate) {
           str +=  (aDate.getFullYear() +  (aDate.getMonth() + 1) + aDate.getDate());
         }
         return str;
       }
     </script>

     /*
      *  Scripts that run on the server.
      *  Jaxer generated stubs are used to call these from the client.
      */
     <script runat='server-proxy'>

       //
       // Server side persistence functions
       //

       // Write a new object to the DB
       function createPerson_Server(person) {
         // execute insert statement, binding to properties of passed in person
         Jaxer.DB.execute(
           'insert into person ( '+
             '  id, first_name, last_name, birth_date, weight_kg, height_m ' +
           ' ) values (?, ?, ?, ?, ?, ?);',
           person.id, person.firstName,
           person.lastName, person.birthDate,
           person.weightInKilograms, person.heightInMeters
         );
       }

       // Read an existing record and return a JavaScript object
       function readPerson_Server(id) {
         // execute query and receive returned a Jaxer.DB.ResultSet
         var resultSet = Jaxer.DB.execute('select * from person where id = ?;', id);
         // select the first row since weonly care about 1 person
         var aRow = resultSet.rows[0];
         // map DB column names to front end column names
         var person = {
           id: aRow.id,
           firstName: aRow.first_name,
           lastName: aRow.last_name,
           birthDate: aRow.birth_date,
           weightInKilograms: aRow.weight_kg,
           heightInMeters: aRow.height_m
         };
         // return to client for display
         return person;
       }

       // From a JS Object, update a row in the DB
       function updatePerson_Server(person) {
         // Update all fields for the given primary key value
         Jaxer.DB.execute(
           'update person set  '+
             '  first_name = ?, last_name = ?, birth_date = ?, weight_kg = ?, height_m = ? ' +
           ' where id = ?;',
           person.firstName, person.lastName, person.birthDate,
           person.weightInKilograms, person.heightInMeters,
           person.id
         );
       }

       // Delete a record in the DB
       function deletePerson_Server(id) {
         Jaxer.DB.execute('delete from person where id = ?;', id);
       }

       //  Create a table if the table is not already in the DB
       function createTable(){
         Jaxer.DB.execute(
           'create table if not exists person (   ' +
           ' id      integer,   ' +
           ' first_name  varchar(20),   ' +
           ' last_name   varchar(20),   ' +
           ' birth_date  datetime,   ' +
           ' weight_kg   decimal(5,2),   ' +
           ' height_m    decimal(5,2),   ' +
           ' constraint person_pk primary key(id)); '
         );
       }
     </script>
     <style>
       .big-cap {
         color: blue;
         font-size:larger;
         font-style:italic;
       }
       body {
         font-family:Arial;
         font-size: 10pt;
       }
     </style>
   </head>
   <body>
     <h3><span class="big-cap">C</span>reate a person from this table</h3>
     <table border="1" style="text-align: center" id="create-table">
       <tr>
         <th>id</th>
         <th>firstName</th>
         <th>lastName</th>
         <th>birthDate</th>
         <th>weightInKilograms</th>
         <th>heightInMeters</th>
       </tr>
       <tr>
         <td>1</td>
         <td>John</td>
         <td>Doe</td>
         <td>1975-11-20</td>
         <td>90.7</td>
         <td>1.82</td>
       </tr>
     </table>
     <hr/>
     <h3><span class="big-cap">R</span>ead a person and populate this table</h3>
     <table border="1" style="text-align: center" id="read-table">
       <tr>
         <th>id</th>
         <th>firstName</th>
         <th>lastName</th>
         <th>birthDate</th>
         <th>weightInKilograms</th>
         <th>heightInMeters</th>
       </tr>
       <tr>
         <td></td>
         <td></td>
         <td></td>
         <td></td>
         <td></td>
         <td></td>
       </tr>
     </table>
     <hr/>
     <h3><span class="big-cap">U</span>pdate a person from this table</h3>
     <table border="1" style="text-align: center" id="update-table">
       <tr>
         <th>id</th>
         <th>firstName</th>
         <th>lastName</th>
         <th>birthDate</th>
         <th>weightInKilograms</th>
         <th>heightInMeters</th>
       </tr>
       <tr>
         <td>1</td>
         <td>Jane</td>
         <td>Smith</td>
         <td>1978-1-1</td>
         <td>89.2</td>
         <td>1.76</td>
       </tr>
     </table>
     <hr/>
     <h3><span class="big-cap">D</span>elete person with id = 1</h3>
     <hr/>
     <button onclick="runExample();">Crud</button>
   </body>
 </html>