Gbatumbya/File:DraftProposal
It contains historical information.
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
