This is the namespace that contains Jaxer serialization methods. The Jaxer serializer uses the familiar and popular JSON format.
However, additional functionality has been provided to allow for serialization of more complex data structures. Specifically,
this module supports cyclical data structures, multiple references, and custom typeserializers. Each of these is described
below. Cyclical data structures occur when an object (or array) contains a descendent structure that also references that
same object. For example, a DOM node has references to its children and these children also have references to the DOM node
(their parentNode). In a traditional JSON environment, if you were to try to serialize this structure, you would end up in
an infinite loop or an exception would occur as the serializer traversed the parent node, its child nodes, and then back up
to the parent node through the child's parentNode property. Indeed, the serializer couldn't get past the first child in this
scenario. The Jaxer serializer bypasses this via the use of marker properties and specially formatted strings referred to
as "references". Multiple references are similar to cyclical data structures in that an object is referenced two or more times.
However, this does not necessarily create a cycle. For example, say you have the following code:
var car = { color: "blue",
price: 10000 }; var cars = [ car, car ] ; As you can see, the same car object has been referenced twice in the array.
In a traditional JSON serializer, each instance of car would be serialized separately. Unfortunately, that alters the data
structure that will be accessed after deserialization in a subtle way. You will end up with two independent car objects which
means that changing the price of one will not change the price of the other as would have happened before the serialization/deserialization
cycle. In order to restore the same references, Jaxer serializes the car only once and then leaves placeholders to point to
that single instance. During deserialization, the placeholders are replaced with actual references to the deserialized object,
thus restoring the original data structure as it appeared before serialization. Some data types cannot be expressed in JSON.
For example, the Date type is not listed as a valid type in JSON. So, in order to support this type and potentially many others,
the serializer allows the developer to register custom serializers and associated deserializers for a given type. When the
serializer sees these types, the custom handlers are used to convert the item to a string. It is then the responsibility of
the custom deserializer to restore the string to the original type. For example, Jaxer supports XMLDocuments. The custom serializer
creates an XML string which is specially tagged so the deserializer can restore the XML string back to an XMLDocument. Next,
we briefly discuss how Jaxer recognizes cycles, multi-references, and how it represents references and custom serialized objects.
The Jaxer serializer makes an initial pass over the data being serialized. Each object, array, and custom serialization object
is tagged with a unique index. (Note that some objects do not allow properties to be added to them. In this situation, the
Jaxer serializer maintains an array of these items. This array is searched when new items are encountered and serves the same
purpose as the id property). Before adding the index, we first check if we have already indexed the item. If the tag already
exists, then we've either exposed a cycle or a multi-reference. At this point, the serializer knows to switch to another JSON
format that minimizes the amount of data to be serialized. References and custom serialization objects each make use of specially
formatted strings. To make this a bit clearer, we create an array of two references to the same date object. var d =
new Date(); var items = [ d, d ] ; var json = Jaxer.Serialization.toJSONString(items); The resulting JSON string will
look like the following: [ [ "~1~","~1~" ] , "~Date:2007-08-17T11:57:30~" ]This format always has a top-level array whose first element is the root item that was originally being serialized. In this case, our top-most element was an array. As an aside, the only top-level elements that can generate this format are arrays, objects, and custom serialization objects. The first special format used for references and is defined with "~ # ~" where # is a number. The number is the index into the top-level array. The element at that index is the item that needs to be referenced where the reference string lives. In this example, once deserialization has completed, both instances of "~1~" will have been replaced with references to the deserialized date object. The next custom format, the date, shows how custom serializers emit text. The first item after the ~ but before the : is the name of the type. This is the fully-qualified type as you would have to type it in JavaScript to get to that type's constructor. The string after the : is in a format as generated by the type's custom serializer. The resulting string generated by the custom serializer is in turn serialized as a string, so the deserializer does not need to handle special characters or escape sequences. It is the responsibility of the custom deserializer to consume that text and to return effectively a clone of the original object. This module also allows a developer to register alternate top-level serialization and deserialization methods. The default method for serialization is 'nativeJSON' which attempts to use the built-in JSON support in the user agent, when available. In cases where 'nativeJSON' is not supported, the 'JSON' mode will be used. The developer can also use 'JSON' along with more options to customize serialization for special values like 'undefined', and 'INFINITY', for example. Finally, there is a 'Jaxer' mode as described above. This mode is used by Jaxer's framework and callback mechanisms and is available to developers that may need this advanced functionality. These serialization methods are specificed in a separate optional parameter to the "toJSONString" and 'fromJSONString" functions. Note that if the developer uses a non-default serialization method, then the developer is also responsible for using this same method for deserialization. Currenty, this implementation cannot detect which method was used for the original serialization step
Platform Support
| Jaxer Server Framework | Jaxer Client Framework | 1.0 | 1.0 |
|---|
Functions
| Method | Action | Jaxer Server Framework | Jaxer Client Framework | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
static addDeserializer(String name, Function deserializer, [Function beforeDeserialization,] [Function afterDeserialization]) :
void
Add a top-level JSON serializer
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
|
||||||||||||||||||
|
static addSerializer(String name, Function serializer, [Function beforeSerialization,] [Function afterSerialization]) :
void
Add a top-level JSON serializer
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
|
||||||||||||||||||
|
static addTypeHandler(String name, Function serializer, Function deserializer, [Function canSerialize,] [Function canDeserialize]) :
void
Add handlers for custom serialization/deserialization
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
|
||||||||||||||||||
|
static fromJSONString(String json, Object options) : Object
Reconstructs a Javascript data structure from a JSON string. Note that the serialization mode ('Jaxer', 'JSON', or 'nativeJSON')
can be specified in the "options" parameter with the 'as' property. This will default to 'nativeJSON' when either no options
are passed in or if the 'as' property is not defined. See Jaxer.Serialization.toJSONString for more details.
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
Returns
|
||||||||||||||||||
|
static removeSerializer(String name) : Boolean
Remove support for the custom JSON serializer
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
Returns
|
||||||||||||||||||
|
static removeTypeHandler(String name) : Boolean
Remove support for custom serialization/deserialization for the specified type
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
Returns
|
||||||||||||||||||
|
static toJSONString(Object data, [Object options]) : String
Convert the specified object into a JSON representation. Note that we have modified JSON to support object references (cycles)
and to convert Dates into a special format that will be recognized by our code during deserialization. This function includes
an optional second parameter which can be used to control how the data is serialized. If the options parameter defines an
'as' property, that will be used to select the serialization format. Currently, the values 'Jaxer', 'JSON', and 'nativeJSON'
are supported. 'Jaxer' includes support for cycles, multi-refs, and custom type serializers. 'JSON' and 'nativeJSON' follow
the serialization format and semantics as defined by Douglas Crockford on the json.org website. When specifying the 'Jaxer'
serializer, additional options are available. The "useCustomSerializers" has a boolean value which defaults to true. When
this property is true, any type serializers that have been registered via addTypeHandler will be used in the serialization
process. When this value is false, items needing custom serialization will be ignored as they would be in the "JSON" format.
The "undefinedSerializationAction" property determines how the 'undefined' value is handled. The action defaults to 'serialize',
but 'throw' is also supported which will throw an exception when trying to serialize 'undefined'. When specifying the 'JSON'
serializer, additional options are available. The 'maxDepth' property, which defaults to 10, is used to prevent deep recursion.
If the recursion level is encountered, the 'maxDepthAction' property determines the serializer's action. 'truncate' will emit
a "__truncated__" string in place of the object that would cause the recursion level to be exceeded. 'throw' will throw an
exception. The 'dateSerializationAction' property is used to determine how dates are processed. A value of 'serialize' will
convert the date to a specially formatted string as described in the json.org example code. A value of 'throw' will throw
an exception when a date is encountered. Finally, a value of "return object" will return an empty object in place of the Date
itself. The 'undefinedSerializationAction' property is used to determine how 'undefined' is processed. A value of 'serialize'
will convert the value to 'undefined'. 'throw' will throw an exception and 'nullify' will return 'null'. The 'specialNumberSerializationAction'
property is used to determine how Infinity, -Infinity, and NaN are processed. A value of 'serialize' will convert the value
to their text representation which is the same as the identifier used to represent them. 'throw' will throw an exception and
'nullify' will return null. When specifying the 'nativeJSON' serializer, the built-in native support for JSON serialization
will be used, when available. This serialization does not support any custom options. In the case where 'nativeJSON' is specified
but is not available, this mode will fallback to the 'JSON' mode with options specified in that mode to match the behavior
of the native JSON implementation as specificed in the ECMAScript 3.1 specification. Note that other serializers can be registered
with Jaxer. Most likely those serializers will define their own set of options. You will need to refer to the implementors
documentation to determine those properties, their values, and their associated semantics.
|
Show Details | 1.0 | 1.0 | |||||||||||||||
|
Parameters
Returns
|
||||||||||||||||||
