When solving various tasks, it's often necessary to implement the same (or quite close) functionality in all the cases. The process of creating particular implementation or method is justified in process of solving typical tasks.

The use of Event API allows simplifying the solution of typical tasks, as well as decreases the amount of mistakes and simplifies the implementation of particular business logic.

Event API is the implementation of pattern Observer (push technology) in JavaScript language for JSON objects. An event-based API gemerates processing events (such as the start and end of JSON node visiting) directly to the application through callbacks (Observer).

An event-based API provides a simple, low-level access to JSON data structure. Such approach has such important advantages as flexibility and universality. Event handlers encapsulate custom business logic and contain only code required for special task.

JSONER includes two versions for work with event-based API:

• Event API for the tree - JSON tree walker.
• Event API for linear structure - JSON path evaluator.

As it could be seen from the name, it is better to use tree-event-based API for treelike data structures, while a list-event-based API suits better for linear structures.

So, tree-event-based API for the tree is similar to XML processing and allows using single interface both for XML and for JSON.

Actually, the same caller code could be used regardless of how underlying data are represented (whether they are in XML or JSON).

A tree-event-based API may be used for comparison JSON objects or transformation JSON into XML or HTML DOM etc.

Using list-event-based API is similar to working with resource bundles, HTML form and, at last, with cookies.

On the basis of list-event-based API the transparent transformation JSON data into a HTML form or cookies may be implemented.

JSON path is a string representation of path within JSON data structure.

From simplicity point of view, it can be described as string representation of dotted notation in JavaScript used for getting access to object properties.

For instance, if the following construction is used for getting the date of birth:

  var date = company.person[27].info.birthday;

then the corresponding JSON path will look like:

  var path="company.person[27].info.birthday";

Probably this is not absolutely correct term, but actually the idea was quite simple - JSONER is stateless, so JSONER object does not cache processed data not in any fields nor in some global scope.

In general, AJAX applications utilize several threads (via timers, of course) and JSONER design guarantees that simultaneous calls of several JSONER method(s) will not lead to some unexpected effects or errors.

Something like this illustrates mentioned above - calling methods from several timers:

  var jTools = new JsonTools();
  var pp = jTools.jsonToXML(json);
  window.setTimeout(
    function()
    {
      var tt = jTools.jsonToXML(json);
    },
    2 ) ;
	window.setTimeout(
    function()
    {
      var m = jTools.jsonToXML(json);
    }
  , 1 ) ;

This term is related to binding data in JSON and form. Of course, there are several solutions of the same problem while selecting the best one for particular task is possible only taking into consideration specifics of particular case.

Well, let's imagine we have a "Person" object with "Billing info". "Billing info" contains information about primary and secondary credit card.

Also, we have some static HTML form (which is used to enter information about "person") and we'd like to populate content of that form to JSON object.

Basically, there are several possible solutions of this task:

1. "Algorithm based approach " copy content from HTML form to JSON object manually in code.

     var person = {person:{name:"John"} };
     if ( form["firstCardNumber"].value !== "" )
     {
     if ( isUndefined(person.billing) )
     {
   	  person.billing = {};
     }
     if ( isUndefined(person.billing.firstCard) )
     {
   	  person.billing.firstCard = {};
     }
     person.billing.firstCard.number =
          form["firstCardNumber"].value;
   }

2. "Full filled JSON "- similar to previous one, but it is simpler since we have all structure to which data will be copied already created/prepared.

     var person = {person:
                   {
                    billing:
                      {
                       firstCard:{},
                       secondCard:{}
                     }
                   }
                 };
     if ( form["firstCardNumber"].value !== "" )
     {
       person.billing.firstCard.number =
          form["firstCardNumber"].value;
     }

3. And this one, using JSONER to perform such copying.

     var  person = { person:{name:"John"} };
     if ( form["firstCardNumber"].value !== "" )
     {
       jTools.setValue(person,
         "billing.firstCard.number",
         form["firstCardNumber"].value);
     }

In addition, later approach could be even more expanded to reduce amount of coding - for example, it's possible to write even more generic algorithm with takes name of form, reference to object and map which could be used to associate names of form files and full paths to JSON object properties (here could be even used some small trick - if field name in HTML form corresponds to full path of property of corresponding JSON object, we will simply need only list of property path names to perform such data binding).

Standard ECMA-262 provides for two variants of getting access to objects properties:

• The dot notation;
• The bracket notation;

JSONER is oriented on the dotted notation, consequently, function and invalid Java Script identificators can't be used for naming the object properties.

The example of invalid (from the point of JSONER) indentificator is given below:

var task = {"task.starting.date":"12-12-93",
            "function":"alertToUser"};

JSONER includes the set of useful methods for processing JSON data:

• Methods for data lookup;
• Methods for data binding;
• Methods of populating data from HTML form to JSON and the contrary;
• Methods for creating HTML forms and other components;
• Methods for comparison JSONs (quite useful when checking if the input data were changed);
• Methods for transformation JSON to XML or HTML string for further processing;
• Methods for transformation array of JSONs to a MAP (quite useful when expanding key to value);
• Methods for obtaining and modifying parts of JSON tree;

Well, yes and no... JSONER includes basic pattern Visitor, which can be defined by parameters in two ways:

• "Acceptor" - method which accepts or rejects processing of particular node;
• "Processor"- method performs necessary operations on given JSON node.

Visitor can be adapted for solving many tasks related to data search and processing. Visitor is very useful when it is necessary to perform operations on tree-based structures, such as, for example, modification of the tree or finding nodes by specified conditions.

Pattern Visitor provides high speed of data access and flexibility when dealing with them. JSONER "lookup functionality" includes method which allow to:

• Find first element which corresponds search conditionsl;
• Find all elements which correspond search conditions
• Find number of elements which correspond search conditions.
• Check if there are elements exist which correspond search conditions.

Code for transforming JSON tree into XML is included into the library, because JSONER implementation is more flexible and faster than similar solutions.

JSONER is Open Source project. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at Apache License 2.0 license. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Well, JSONER was tested under:

• By JsLint
• Windows Internet Explorer 6.0/7.0
• Mozilla Firefox 1.5/2.0
• Safari 2.0.3

Let us know it! Please submit bugs and feature ideas or patches to the email [email protected], and we’ll get on it.

Please do not hesitate contacting us if you have any questions, comments, suggestions or simply find some issues with JSONER. Please send us your feedback via email using [email protected] email addresss.