Circular References

jabsorb 1.2 introduces support for passing data structures with circular references across the JSON-RPC data stream.

An extension to standard JSON-RPC is used to accomplish this. We call this the "fixups" method.

Duplicate references are also handled via this same scheme to allow more efficient and accurate transfer of objects graphs.

Because JSON and standard JSON-RPC do not support circular references, using this fixups method results in a data protocol that is not 100% compatible with other standard JSON-RPC implementations when data structures with these circular references are used.

You can disable these fixups for circular references or duplicate references, or both, if desired.

NOTE that if you pass an object that does not have any circular references or duplicates in it-- even if circular reference and duplicate checking is turned on, the resultant data stream will still be 100% standard JSON-RPC compliant.

By default, fixup checking is turned on and used on both the client and server for both circular references and duplicate references.

To disable transmission of circular references or fixups of duplicate references from Java server to the browser client, set one or both of these options on the JSONSerializer:

// get the system JSONSerializer that is used in the JSONRPCBridge  
JSONSerializer ser = JSONRPCBridge.getSerializer();

// disable circular references when marshalling java to json
// if circular references are found, an exception will be thrown
// like in jabsorb 1.1 and earlier
ser.setFixupCircRefs(false);

// disable duplicate references when marshalling java to json
// if duplicates are found, they will just be reserialized, like
// in jabsorb 1.1 and earlier
ser.setFixupDuplicates(false);

NOTE Starting with jabsorb 1.2.1, primitive java wrapper Object types (String, Boolean, Integer, Boolean, Long, Byte, Double, Float and Short) will not be fixed up by default, even if they are duplicate references. This behavior can be changed (see below.)

// (added in 1.2.1)
// by default, the immutable primitive wrapper types aren't fixed up
// even if they *are* duplicates.
// this default behavior can be changed-- the following will enable 
// fixups for the primitive wrapper types 
// (String, Boolean, Integer, Boolean, Long, Byte, Double, Float and Short) 
ser.setFixupDuplicatePrimitives(true);
    
// note that the above call will be meaningless if duplicate checking is 
// turned off altogether.

To disable transmission of circular references or fixups of duplicate references from the browser client to the Java server, set one or both of the options in your JavaScript client code after jsonrpc.js is loaded (or modify your copy of jsonrpc.js):

// if this is true, circular references in the object graph are fixed up
// if this is false, circular references cause an exception to be thrown
JSONRpcClient.fixupCircRefs = false;

// if this is true, duplicate objects in the object graph are optimized
// if it's false, then duplicate objects are "re-serialized"
JSONRpcClient.fixupDuplicates = false;

Setting all of these flags to false will cause jabsorb be a strictly compliant JSON-RPC processor, like in version 1.1.x and earlier-- albeit with much better detection and exception handling if any circular references are found.