ObjectMarshaller, formerly EZObjectMarshaller in vilya + some value validation code

that was actually in GameControlBackend.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@4748 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/as/com/threerings/util/ObjectMarshaller.as

@@ -0,0 +1,174 @@
+//
+// $Id$
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.util {
+
+import flash.net.ObjectEncoding;
+
+import flash.system.ApplicationDomain;
+
+import flash.utils.ByteArray;
+import flash.utils.Endian;
+import flash.utils.IExternalizable;
+import flash.utils.getQualifiedSuperclassName; // function import
+
+import com.threerings.io.TypedArray;
+
+/**
+ * Utility methods for transforming flash objects into byte[].
+ */
+public class ObjectMarshaller
+{
+    /**
+     * Encode the specified object as either a byte[] or a byte[][] (see below).
+     * The specific mechanism of encoding is not important,
+     * as long as decode returns a clone of the original object.
+     *
+     * No validation is done to verify that the object can be serialized.
+     *
+     * Currently, cycles in the object graph are preserved on the other end.
+     *
+     * @param encodeArrayElements if true and the obj is an Array, each element is
+     * encoded separately, returning a byte[][] instead of a byte[].
+     */
+    public static function encode (
+        obj :Object, encodeArrayElements :Boolean = false) :Object
+    {
+        if (obj == null) {
+            return null;
+        }
+        if (encodeArrayElements && obj is Array) {
+            var src :Array = (obj as Array);
+            var dest :TypedArray = TypedArray.create(ByteArray);
+            for each (var o :Object in src) {
+                dest.push(encode(o, false));
+            }
+            return dest;
+        }
+
+        // TODO: Our own encoding, that takes into account
+        // the ApplicationDomain.. ACK
+        var bytes :ByteArray = new ByteArray();
+        bytes.endian = Endian.BIG_ENDIAN;
+        bytes.objectEncoding = ObjectEncoding.AMF3;
+        bytes.writeObject(obj);
+        return bytes;
+    }
+
+    /**
+     * Validate the value and encode it. Arrays are not broken-up.
+     */
+    public static function validateAndEncode (obj :Object) :ByteArray
+    {
+        validateValue(obj);
+        return encode(obj, false) as ByteArray;
+    }
+
+    /**
+     * Decode the specified byte[] or byte[][] back into a flash Object.
+     */
+    public static function decode (encoded :Object) :Object
+    {
+        if (encoded == null) {
+            return null;
+        }
+        if (encoded is TypedArray) {
+            var src :TypedArray = (encoded as TypedArray);
+            var dest :Array = [];
+            for each (var b :ByteArray in src) {
+                dest.push(decode(b));
+            }
+            return dest;
+        }
+        var bytes :ByteArray = (encoded as ByteArray);
+        // re-set the position in case we're decoding the actual same byte
+        // array used to encode (and not a network reconstruction)
+        bytes.position = 0;
+
+        // TODO: Our own decoding, that takes into account
+        // the ApplicationDomain.. ACK
+        bytes.endian = Endian.BIG_ENDIAN;
+        bytes.objectEncoding = ObjectEncoding.AMF3;
+        return bytes.readObject();
+    }
+
+    /**
+     * Validate that the value is kosher for encoding, or throw an ArgumentError if it's not.
+     */
+    public static function validateValue (value :Object) :void
+        // throws ArgumentError
+    {
+        var s :String = getValidationError(value);
+        if (s != null) {
+            throw new ArgumentError(s);
+        }
+    }
+
+    /**
+     * Get the String reason why this value is not encodable, or null if no error.
+     */
+    public static function getValidationError (value :Object) :String
+    {
+        if (value == null) {
+            return null;
+
+        } else if (value is IExternalizable) {
+            return "IExternalizable is not yet supported";
+
+        } else if (value is Array) {
+            if (ClassUtil.getClassName(value) != "Array") {
+                // We can't allow arrays to be serialized as IExternalizables
+                // because we need to know element values (opaquely) on the
+                // server. Also, we don't allow other types because we wouldn't
+                // create the right class on the other side.
+                return "Custom array subclasses are not supported";
+            }
+            // then, continue on with the sub-properties check (below)
+
+        } else {
+            var type :String = typeof(value);
+            if (type == "number" || type == "string" || type == "boolean" ) {
+                return null; // kosher!
+            }
+            if (value is ByteArray) {
+                return null; // kosher
+            }
+            var clazz :Class = ClassUtil.getClass(value);
+            var clazzparentname :String = getQualifiedSuperclassName(clazz);
+            var rootclass :Boolean = (clazzparentname == null);
+            if (! rootclass) {
+                return "Non-simple properties may not be set.";
+            }
+            // fall through and verify the object's sub-properties
+        }
+
+        // check sub-properties (of arrays and objects)
+        for each (var arrValue :Object in (value as Array)) {
+            var s :String = getValidationError(arrValue);
+            if (s != null) {
+                return s;
+            }
+        }
+
+        return null; // it all checks out!
+    }
+}
+}