View source for Gbatumbya/File:DraftProposal

{{Admon/obsolete}}


JSON Adapter – Ability to Access NexJ Express Server Objects Via JSON
(the 1st Draft – July 19th, 2010)

Overview

This project proposal outlines the process of developing a JSON Adapter for the Nexj Express Server. The adapter will add the ability to access NexJ Express Server objects as JSON representation via a RESTful web services.

About JSON

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999.

JSON is a text format that is completely language independent and it is built on two structures:

A 	collection of name/value pairs. In various languages, this is 	realized as an object, record, struct, dictionary, hash 	table, keyed list, or associative array.

An 	ordered list of values. In most languages, this is realized as an 	array, vector, list, or sequence.

These are universal data structures. Virtually all modern programming languages support them in one form or another. It makes sense that a data format that is interchangeable with programming languages also be based on these structures.

Project Proposal

The project proposal contains four parts: (1) Tools, (2) Serialization, (3) RESTful Webservice, (4) JUnit test.

Part 1 – JSON Tools

Roles:

low level functionality for the ability to render, parse and validate JSON representation.

The JSON tool package will contain a JSON renderer for writing basic JSON types, a JSON parser, a JSON validator, and other functional components as they become necessary. These are basic utility classes for dealing with JSON type representations:

JSON Renderer

Task:

Renders input information into JSON representation. (Ideally, the input information could be of any type)

Method will implement rendering JSON representation for:

Complex 	Data

Object

Array

Simple 	Date

Write 		Null

Write 		Boolean

Write 		String

Write 		Number

Integer

Decimal

JSON Parser

Task:

Add the ability to parse JSON into a Request object

This class parses JSON into a Map.

JSON Validator

Task:

Add the ability to validate formal JSON representation. If a Schema (NexJ rules) becomes available the validation could be extended.

This class will be developed if the time permits at the end of the first cycle.

Design Principals for JSON Tools:

JSON 	format should be clean (no meta information can be stored). If a 	trade-off has to be made, it will be in favor of cleanest and 	straightforward JSON format.

The 	JSON string representation should not be dependent on the Java 	object (i.e., the design must not try to map one to one the Java 	types into JSON format).

The 	parser will not deal with the recursive structures or the difference 	between reference types and primitives. The mapper will use a 	repository of helpers, where each helper must be specialized in 	mapping of a certain class or interfaces.

Part 2 – JSON Serializer/Deserializer

Roles: the implementation of the serialization process. The serialization package will contain classes for marshalling server response into JSON format and unmarshalling client request from JSON format

JSON Marshaller

Class name: JSONMarshaller

This class serializes a response object in JSON representation.

Task:

Implement object specific marshallers for:

String, Binary, PagedBinary, Integer, Long, BigDecimal, Float, Double, java.sql.Date, java.sql.Time, java.sql.Timestamp, Boolean, ArrayList, PagedArrayList, Object[], String[], Character, char[], StringId, Symbol, Locale, TimeZone, Pair, ConstPair, PrivilegeSet, PCodeFunction, PCodeMacro, OID, TransferObject, Request, Response, SOAPRequest, SOAPResponse, SOAPFault.

(same as implemented for SOAPMarshaller and XMLMarshaller)

JSON Unmarshaller

Class name: JSONUnmarshaller

This class deserializes objects from JSON representation into Request object.

Task:

Implement object specific unmarshaller helpers from JSON representation for all the basic classes mentioned above. All helper (inner) classes must be designed to optimize the creation of the Request object for a RESTful style invocation.

Design Principals for JSON Serializer/Deserializer:

NexJ 	internal object representation must be preserved by 	serializer/deserializer.

The 	serialization tool should also preserve the difference between 	primitive and reference types.

The 	recursive types should be supported (attention to infinite loop in 	recursive serialization and instance identity preservation).

The 	serialization/deserialization process must be easily extended; i.e., 	a design pattern must be implemented so that any data type could be 	straightforwardly added at any given time as the server requires.

Part 3 – RESTful Web Service

To be defined after the revision and approval of the first two parts.

Part 4 – JUnit Test for each project component

Each functional component previously mentioned will have a corresponded JUnit test element. If and only if a functional unit passes all the tests, then the unit could be considered as a release candidate.

CDOT – Seneca College

July 19, 2010