JSON Integration Adapter

Project Goal

To create an adapter for the NexJ Core similar in methodology and design of existing message adapters (XML, Fixed, CSV etc.) but using the JSON format

Contributors

Current Status

Parser and formatter functional

Remaining Tasks as of 7.19.2011

Clean up baseTypes.xsd
Complete XMLJSONMessageMappingLoader
1. Complete mapping part validation
2. Complete loader method
Make sure root as array really works with parser
Make sure typed array really works with parser
1. Make sure typed array validates that all array contents are the same object
Deal with CYCLIC REFERENCES
Deal with message nodes with the same name at the same level (perhaps not a problem with new algorithm)
Deal with Transfer Object OID
Line-by-line internal review of code
1. Formatter
2. Parser
Create more complex unit tests and consolidate unit tests
Create integration test with NexJ Express using channels, etc.

Project Phases

JSON Integration Adapter Phases

Phase I. Research (DONE)

Complete Fundamentals of NexJ Studio tutorial
Complete NexJ Integration tutorial
Install NexJ Studio Express from source

Phase II. Design Proposal (DONE)

Receive general approval for project
Receive approval for JSON encoding options
Receive approval for JSON formatting options
Final Project Proposal

Phase III. Message Formatter (DONE)

Add JSON to .XSD base types
Create sample JSON .message
Parse sample JSON .message with JUnit Test
Create first set of unit tests for Message Formatter
Code Message Formatter first draft
Resolve issues with first set of unit tests
Create second set of unit tests
Resolve issues with second set of unit tests
Refactor and code message formatter

Phase IV. Message Parser (DONE)

Discover how to connect JSON RPC parser with Message Parser
Create first set of trivial unit tests for Message Parser
Code Message Parser skeleton
Pass first set of trivial unit tests
Create second set of unit tests (non-trivial) for Message Parser
Code Message Formatter first draft
Resolve issues with second set of unit tests
Refactor

Phase V. Integration and Stress Tests (IN PROGRESS)

Test Message Formatter and Message Parser with integration and stress tests
Test through NexJ Studio Express GUI (manual testing)

Phase VI. Internal Code Review

Internally review code at CDOT

Phase VII. Optimization

Find more code optimizations relevant to Enterprise environments

Phase VIII. First Code Review at NexJ

Date TBA

Phase IX. Code Rewrite

Rewrite code to conform with NexJ suggestions and standards

Phase X. Second Code Review at NexJ

Date TBA

Phase XI. Project Completion

Project Repository

BitBucket : https://bitbucket.org/b_lim/nexj-express-json-integration-adapter/

Technical Notes

Definitions

Term	Description
Formatter	Turns data into JSON
Parser	Turns JSON into data
Message	The metadata to be used when formatting and parsing a message. The grammar. It is a tree-like structure.
MessageInstance	The information to be parsed or formatted

Because the Integration layer allows a Model to interact with external applications asynchronously, a description / grammar of the data to be exchanged between the two systems is defined using a Message in the Model.

Formatting is turning internal NexJ representation of a MessageInstance into JSON. The formatter is given a Message (the grammar), MessageInstance (the data), and a pipe. This accomplished by walking the Message tree-like structure while validating the data in the MessageInstance and streaming JSON format to the pipe. If the data in the MessageInstance does not conform to the Message, the formatter throws an exception.

Parsing is turning JSON representation of a MessageInstance into an internal NexJ representation of a MessageInstance. The parser is given a Message (the grammar) and an input stream. First the input stream is parsed for JSON using a JSONParser which returns either an Object or an Array. The formatter walks the Message building the structure of the MessageInstance and adding validated values in the object returned by the JSONParser to the MessageInstance. If the data from the input stream does not match the expected input at any time, the parser throws an exception.

Message Fundamentals

Message - Messages can contain values or other messages. The red nodes are messages, the green nodes are values.

Internally, messages are Transfer Objects. To determine if a node is a message, use instanceof on CompositeMessagePartInstance after retrieving the MessagePart. For example,

public void format(TransferObject tobj, Message message, Output out) throws IntegrationException
{
...
CompositeMessagePart root = message.getRoot(); // Gets the root of the message.
Iterator it = root.getPartIterator();
while (it.hasNext())
{
  part = (MessagePart)it.next());
  if (part instanceof CompositeMessagePartInstance)
  {
    // This part is a message
  }
  else if (part instanceof PrimitiveMessagePart)
  {
    // This part is a value
  }
...
}
...

NOTE: THE MESSAGE PARAMETER DOES NOT CONTAIN THE MESSAGE VALUES. THE MESSAGE PARAMETER CONTAINS THE MESSAGE METADATA. THE TRANSFER OBJECT CONTAINS THE MESSAGE VALUES WHICH MUST BE VALIDATED AGAINST THE MESSAGE TO ENSURE CORRECT FORMAT.

MessagePart: Parts of a message. Messages can contain values or other messages. NexJ Express has two types of message parts, CompositeMessagePart and PrimitiveMessagePart.

CompositeMessagePart: implementation is CompositeMessagePartInstance . The relationship between CompositeMessagePartInstance and PrimitiveMessagePart with the above picture is as follows - CompositeMessagePartInstance are messages (the red nodes) and PrimitiveMessagePart are values (the green nodes). To determine multiplicity of MessageParts, use isCollection() method of MessagePart. Note that multiplicity of the above screenshot are all [0..1], that is zero or one instance. Possible node multiplicities:
[0..1]: zero or one instance (i.e. an optional entry)
[1..1]: exactly one instance (i.e. required)
[1..N]: collection of at least one, at most N instances
[0..0]: collection of zero to infinite instances (displayed as [*])
[1..0]: collection of at least one, possibly unlimited instances

XMLJSONMessageMappingLoader: Used by the framework to autoload JSONMessagePartMapping for each of the message parts.

JSONMessagePartMapping: Each node in the above picture may has a corresponding JSONMessagePartMapping. Each node may have its own mapping, with its own values initialized in XMLJSONMessageMappingLoader. In order to get the mapping, first cast MessagePart to a concrete class such as CompositeMessagePartInstance or PrimitiveMessagePart, then use part.getMapping(). The purpose of the mapping is metadata for each node.

JSONMessageFormatter: Used to turn messages into JSON format.

JSONMessageParser: Used to turn JSON into a message.

Algorithm

format(TransferObject tobj, Message message, Output out) Algorithm for format method is as follows

Retrieve the root of the message
Iterate through each of the parts of the root
1. If the part is a CompositeMessagePartInstance, it is a message node
2. If the part is a PrimitiveMessagePart, it is a value node
3. Validate the part against the MessagePartMapping. Different types of validation must be done if the part is a Composite versus if it is a Primitive.
4. If the part is a CompositeMessagePartInstance, recursively call the format method with TransferObject set to the part. Suggested to overload the format method to format(TransferObject tobj, MessagePart message, Output out) and pass in the part, since retrieving a message root with getRoot() will always get the highest root of the message but what you want is the parent.
5. If the part is a PrimitiveMessagePart, write the message part to the output.

Resources

JSON RFC : http://www.ietf.org/rfc/rfc4627.txt
Introduction to NexJ Studio Express : https://www.projects.openhealthtools.org/sf/go/doc1771?nav=1
NexJ Developer's Guide
NexJ Integration Fundamentals
Open Health Tools Integration Platform https://www.projects.openhealthtools.org/sf/projects/oht_aip/

CDOT Wiki β