Using native JSON functionality
ActionScript 3.0 provides a native API for encoding and decoding ActionScript objects using JavaScript Object Notation (JSON) format. The JSON class and supporting member functions follow the ECMA-262 5th edition specification with few variances.
Community member Todd Anderson provides a comparison
of the native JSON API and the third-party
as3corelib JSON class. See
Working with Native JSON in Flash Player 11.
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:
Defining or overriding
toJSON()on your custom subclass of a non-final native classDefining or redefining
toJSON()on the class prototypeDefining a
toJSONproperty on a dynamic classUsing the
JSON.stringify() replacerandJSON.parser() reviverparameters
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:
MovieClip.prototype.toJSON = function(k):* {
trace("prototype.toJSON() called.");
return "toJSON";
}
When your application then calls stringify() on any MovieClip instance,
stringify() returns the output of your toJSON() method:
var mc:MovieClip = new MovieClip();
var js:String = JSON.stringify(mc); //"prototype toJSON() called."
trace("js: " + js); //"js: toJSON"
You can also override toJSON() in native classes that define the method. For
example, the following code overrides Date.toJSON():
Date.prototype.toJSON = function (k):* {
return "any date format you like via toJSON: "+
"this.time:"+this.time + " this.hours:"+this.hours;
}
var dt:Date = new Date();
trace(JSON.stringify(dt));
// "any date format you like via toJSON: this.time:1317244361947 this.hours:14"
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:
package
{
import flash.utils.ByteArray;
public class MyByteArray extends ByteArray
{
public function MyByteArray() {
}
public function toJSON(s:String):*
{
return "MyByteArray";
}
}
}
var ba:ByteArray = new ByteArray();
trace(JSON.stringify(ba)); //"ByteArray"
var mba:MyByteArray = new MyByteArray(); //"MyByteArray"
trace(JSON.stringify(mba)); //"MyByteArray"
If a class is dynamic, you can add a toJSON property to an object of that
class and assign a function to it as follows:
var d:Dictionary = new Dictionary();
trace(JSON.stringify((d))); // "Dictionary"
d.toJSON = function(){return {c : "toJSON override."};} // overrides existing function
trace(JSON.stringify((d))); // {"c":"toJSON override."}
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:
JSON.stringify(d, function (k,v):* {
return "any date format you like via replacer: "+
"holder[k].time:"+this[k].time + " holder[k].hours:"+this[k].hours;
});
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().
package {
// Generic dictionary example:
public class JSONGenericDictExample {
static var revivableObjects = [];
static var nextId = 10000;
public var id;
public var dname:String;
public var birthday;
public function JSONGenericDictExample(name, birthday) {
revivableObjects[nextId] = this;
this.id = "id_class_JSONGenericDictExample_" + nextId;
this.dname = name;
this.birthday = birthday;
nextId++;
}
public function toString():String { return this.dname; }
public static function revive(id:String):JSONGenericDictExample {
var r:RegExp = /^id_class_JSONGenericDictExample_([0-9]*)$/;
var res = r.exec(id);
return JSONGenericDictExample.revivableObjects[res[1]];
}
}
}
package {
import flash.utils.Dictionary;
import flash.utils.ByteArray;
// For this extension of dictionary, we serialize the contents of the
// dictionary by using toJSON
public final class JSONDictionaryExtnExample extends Dictionary {
public function toJSON(k):* {
var contents = {};
for (var a in this) {
contents[a.id] = this[a];
}
// We also wrap the contents in an object so that we can
// identify it by looking for the marking property "class E"
// while in the midst of JSON.parse.
return {"class JSONDictionaryExtnExample": contents};
}
// This is just here for debugging and for illustration
public function toString():String {
var retval = "[JSONDictionaryExtnExample <";
var printed_any = false;
for (var k in this) {
retval += k.toString() + "=" +
"[e="+this[k].earnings +
",v="+this[k].violations + "], "
printed_any = true;
}
if (printed_any)
retval = retval.substring(0, retval.length-2);
retval += ">]"
return retval;
}
}
}
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.
import flash.display.MovieClip;
import flash.text.TextField;
var a_bob1:JSONGenericDictExample = new JSONGenericDictExample("Bob", new Date(Date.parse("01/02/1934")));
var a_bob2:JSONGenericDictExample = new JSONGenericDictExample("Bob", new Date(Date.parse("05/06/1978")));
var a_jen:JSONGenericDictExample = new JSONGenericDictExample("Jen", new Date(Date.parse("09/09/1999")));
var e = new JSONDictionaryExtnExample();
e[a_bob1] = {earnings: 40, violations: 2};
e[a_bob2] = {earnings: 10, violations: 1};
e[a_jen] = {earnings: 25, violations: 3};
trace("JSON.stringify(e): " + JSON.stringify(e)); // {"class JSONDictionaryExtnExample":
//{"id_class_JSONGenericDictExample_10001":
//{"earnings":10,"violations":1},
//"id_class_JSONGenericDictExample_10002":
//{"earnings":25,"violations":3},
//"id_class_JSONGenericDictExample_10000":
// {"earnings":40,"violations":2}}}
var e_result = JSON.stringify(e);
var e1 = new JSONDictionaryExtnExample();
var e2 = new JSONDictionaryExtnExample();
// It's somewhat easy to convert the string from JSON.stringify(e) back
// into a dictionary (turn it into an object via JSON.parse, then loop
// over that object's properties to construct a fresh dictionary).
//
// The harder exercise is to handle situations where the dictionaries
// themselves are nested in the object passed to JSON.stringify and
// thus does not occur at the topmost level of the resulting string.
//
// (For example: consider roundtripping something like
// var tricky_array = [e1, [[4, e2, 6]], {table:e3}]
// where e1, e2, e3 are all dictionaries. Furthermore, consider
// dictionaries that contain references to dictionaries.)
//
// This parsing (or at least some instances of it) can be done via
// JSON.parse, but it's not necessarily trivial. Careful consideration
// of how toJSON, replacer, and reviver can work together is
// necessary.
var e_roundtrip =
JSON.parse(e_result,
// This is a reviver that is focused on rebuilding JSONDictionaryExtnExample objects.
function (k, v) {
if ("class JSONDictionaryExtnExample" in v) { // special marker tag;
//see JSONDictionaryExtnExample.toJSON().
var e = new JSONDictionaryExtnExample();
var contents = v["class JSONDictionaryExtnExample"];
for (var i in contents) {
// Reviving JSONGenericDictExample objects from string
// identifiers is also special;
// see JSONGenericDictExample constructor and
// JSONGenericDictExample's revive() method.
e[JSONGenericDictExample.revive(i)] = contents[i];
}
return e;
} else {
return v;
}
});
trace("// == Here is an extended Dictionary that has been round-tripped ==");
trace("// == Note that we have revived Jen/Jan during the roundtrip. ==");
trace("e: " + e); //[JSONDictionaryExtnExample <Bob=[e=40,v=2], Bob=[e=10,v=1],
//Jen=[e=25,v=3]>]
trace("e_roundtrip: " + e_roundtrip); //[JSONDictionaryExtnExample <Bob=[e=40,v=2],
//Bob=[e=10,v=1], Jen=[e=25,v=3]>]
trace("Is e_roundtrip a JSONDictionaryExtnExample? " + (e_roundtrip is JSONDictionaryExtnExample)); //true
trace("Name change: Jen is now Jan");
a_jen.dname = "Jan"
trace("e: " + e); //[JSONDictionaryExtnExample <Bob=[e=40,v=2], Bob=[e=10,v=1],
//Jan=[e=25,v=3]>]
trace("e_roundtrip: " + e_roundtrip); //[JSONDictionaryExtnExample <Bob=[e=40,v=2],
//Bob=[e=10,v=1], Jan=[e=25,v=3]>]
More Help topics
