Overview of the JSON API

The ActionScript JSON API consists of the JSON class and toJSON() member functions
on a few native classes. For applications that require a custom
JSON encoding for any class, the ActionScript framework provides
ways to override the default encoding.

The JSON class internally handles import and export for any ActionScript
class that does not provide a toJSON() member.
For such cases, JSON traverses the public properties of each object
it encounters. If an object contains other objects, JSON recurses
into the nested objects and performs the same traversal. If any object
provides a toJSON() method, JSON uses that custom
method instead of its internal algorithm.

The JSON interface consists of an encoding method, stringify(),
and a decoding method, parse(). Each of these methods
provides a parameter that lets you insert your own logic into the
JSON encoding or decoding workflow. For stringify(),
this parameter is named replacer; for parse(),
it is reviver. These parameters take a function
definition with two arguments using the following signature:

function(k, v):*

toJSON() methods

The signature for toJSON() methods is

public function toJSON(k:String):*

JSON.stringify() calls toJSON(),
if it exists, for each public property that it encounters during
its traversal of an object. A property consists of a key-value pair.
When stringify() calls toJSON(),
it passes in the key, k, of the property that it
is currently examining. A typical toJSON() implementation evaluates
each property name and returns the desired encoding of its value.

The toJSON() method can return a value of any
type (denoted as *)—not just a String. This variable return type
allows toJSON() to return an object if appropriate.
For example, if a property of your custom class contains an object
from another third-party library, you can return that object when toJSON() encounters
your property. JSON then recurses into the third-party object. The encoding
process flow behaves as follows:

If toJSON() returns an object that doesn’t
evaluate to a string, stringify() recurses into
that object.

If toJSON() returns a string, stringify() wraps
that value in another string, returns the wrapped string, and then
moves to the next value.

In many cases, returning an object is preferable to returning
a JSON string created by your application. Returning an object takes
leverages the built-in JSON encoding algorithm and also allows JSON
to recurse into nested objects.

The toJSON()method is not defined in the Object
class or in most other native classes. Its absence tells JSON to
perform its standard traversal over the object's public properties.
If you like, you can also use toJSON() to expose
your object’s private properties.

A few native classes pose challenges that the ActionScript libraries
can't solve effectively for all use cases. For these classes, ActionScript
provides a trivial implementation that clients can reimplement to
suit their needs. The classes that provide trivial toJSON() members
include:

ByteArray

Date

Dictionary

XML

You can subclass the ByteArray class to override its toJSON() method,
or you can redefine its prototype. The Date and XML classes, which
are declared final, require you to use the class prototype to redefine toJSON().
The Dictionary class is declared dynamic, which gives you extra
freedom in overriding toJSON().

Defining custom JSON behavior

To implement your own JSON encoding and decoding for native
classes, you can choose from several options:

Using the JSON.stringify() replacer and JSON.parser() reviver parameters

Defining toJSON() on the prototype of a built-in class

The native JSON implementation in ActionScript mirrors
the ECMAScript JSON mechanism defined in ECMA-262, 5th edition.
Since ECMAScript doesn't support classes, ActionScript defines JSON
behavior in terms of prototype-based dispatch. Prototypes are precursors
to ActionScript 3.0 classes that allow simulated inheritance as
well as member additions and redefinitions.

ActionScript allows you to define or redefine toJSON() on
the prototype of any class. This privilege applies even to classes
that are marked final. When you define toJSON() on
a class prototype, your definition becomes current for all instances
of that class within the scope of your application. For example,
here's how you can define a toJSON() method on
the MovieClip prototype:

Defining or overriding toJSON() at the class level

Applications aren't always required to use prototypes to
redefine toJSON(). You can also define toJSON() as
a member of a subclass if the parent class is not marked final.
For example, you can extend the ByteArray class and define a public toJSON() function:

You can override, define, or redefine toJSON() on
any ActionScript class. However, most built-in ActionScript classes
don't define toJSON(). The Object class does not
define toJSON in its default prototype or declare
it as a class member. Only a handful of native classes define the
method as a prototype function. Thus, in most classes you can’t
override toJSON() in the traditional sense.

Native classes that don’t define toJSON() are
serialized to JSON by the internal JSON implementation. Avoid replacing
this built-in functionality if possible. If you define a toJSON() member,
the JSON class uses your logic instead of its own functionality.

Using the JSON.stringify() replacer parameter

Overriding toJSON() on the prototype is
useful for changing a class’s JSON export behavior throughout an
application. In some cases, though, your export logic might apply
only to special cases under transient conditions. To accommodate
such small-scope changes, you can use the replacer parameter
of the JSON.stringify() method.

The stringify() method applies the function
passed through the replacer parameter to the object
being encoded. The signature for this function is similar to that
of toJSON():

function (k,v):*

Unlike toJSON(), the replacer function
requires the value, v, as well as the key, k.
This difference is necessary because stringify() is
defined on the static JSON object instead of the object being encoded.
When JSON.stringify() calls replacer(k,v),
it is traversing the original input object. The
implicit this parameter passed to the replacer function
refers to the object that holds the key and value. Because JSON.stringify() does
not modify the original input object, that object remains unchanged
in the container being traversed. Thus, you can use the code this[k]to
query the key on the original object. The v parameter
holds the value that toJSON() converts.

Like toJSON(), the replacer function
can return any type of value. If replacer returns
a string, the JSON engine escapes the contents in quotes and then
wraps those escaped contents in quotes as well. This wrapping guarantees that stringify() receives
a valid JSON string object that remains a string in a subsequent
call to JSON.parse().

The following code uses the replacer parameter
and the implicit this parameter to return the time and hours values
of a Date object:

Using the JSON.parse() reviver parameter

The reviver parameter of the JSON.parse() method
does the opposite of the replacer function: It
converts a JSON string into a usable ActionScript object. The reviver argument
is a function that takes two parameters and returns any type:

function (k,v):*

In this function, k is a key, and v is
the value of k. Like stringify(), parse() traverses
the JSON key-value pairs and applies the reviver function—if
one exists—to each pair. A potential problem is the fact that the
JSON class does not output an object’s ActionScript class name.
Thus, it can be challenging to know which type of object to revive.
This problem can be especially troublesome when objects are nested.
In designing toJSON(), replacer,
and reviver functions, you can devise ways to identify
the ActionScript objects that are exported while keeping the original
objects intact.

Parsing example

The following example shows a strategy for reviving objects
parsed from JSON strings. This example defines two classes: JSONGenericDictExample
and JSONDictionaryExtnExample. Class JSONGenericDictExample is a
custom dictionary class. Each record contains a person’s name and
birthday, as well as a unique ID. Each time the JSONGenericDictExample
constructor is called, it adds the newly created object to an internal
static array with a statically incrementing integer as its ID. Class
JSONGenericDictExample also defines a revive() method
that extracts just the integer portion from the longer id member.
The revive() method uses this integer to look up
and return the correct revivable object.

Class JSONDictionaryExtnExample extends the ActionScript Dictionary
class. Its records have no set structure and can contain any data.
Data is assigned after a JSONDictionaryExtnExample object is constructed,
rather than as class-defined properties. JSONDictionaryExtnExample
records use JSONGenericDictExample objects as keys. When a JSONDictionaryExtnExample
object is revived, the JSONGenericDictExample.revive() function
uses the ID associated with JSONDictionaryExtnExample to retrieve
the correct key object.

Most importantly, the JSONDictionaryExtnExample.toJSON() method returns
a marker string in addition to the JSONDictionaryExtnExample object. This
string identifies the JSON output as belonging to the JSONDictionaryExtnExample
class. This marker leaves no doubt as to which object type is being processed
during JSON.parse().

When the following runtime script calls JSON.parse() on
a JSONDictionaryExtnExample object, the reviver function
calls JSONGenericDictExample.revive() on each object
in JSONDictionaryExtnExample. This call extracts the ID that represents
the object key. The JSONGenericDictExample.revive()function
uses this ID to retrieve and return the stored JSONDictionaryExtnExample
object from a private static array.