Java tutorial
/* * jabsorb - a Java to JavaScript Advanced Object Request Broker * http://www.jabsorb.org * * Copyright 2007-2008 The jabsorb team * * based on original code from * JSON-RPC-Java - a JSON-RPC to Java Bridge with dynamic invocation * * Copyright Metaparadigm Pte. Ltd. 2004. * Michael Clark <michael@metaparadigm.com> * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * */ package org.jabsorb.ng; import java.io.IOException; import java.io.ObjectInputStream; import java.io.Serializable; import java.util.ArrayList; import java.util.HashMap; import java.util.HashSet; import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.NoSuchElementException; import java.util.Set; import org.jabsorb.ng.logging.ILogger; import org.jabsorb.ng.logging.LoggerFactory; import org.jabsorb.ng.serializer.MarshallException; import org.jabsorb.ng.serializer.ObjectMatch; import org.jabsorb.ng.serializer.ProcessedObject; import org.jabsorb.ng.serializer.Serializer; import org.jabsorb.ng.serializer.SerializerState; import org.jabsorb.ng.serializer.UnmarshallException; import org.jabsorb.ng.serializer.impl.ArraySerializer; import org.jabsorb.ng.serializer.impl.BeanSerializer; import org.jabsorb.ng.serializer.impl.BooleanSerializer; import org.jabsorb.ng.serializer.impl.DateSerializer; import org.jabsorb.ng.serializer.impl.DictionarySerializer; import org.jabsorb.ng.serializer.impl.EnumSerializer; import org.jabsorb.ng.serializer.impl.ListSerializer; import org.jabsorb.ng.serializer.impl.MapSerializer; import org.jabsorb.ng.serializer.impl.NumberSerializer; import org.jabsorb.ng.serializer.impl.PrimitiveSerializer; import org.jabsorb.ng.serializer.impl.RawJSONArraySerializer; import org.jabsorb.ng.serializer.impl.RawJSONObjectSerializer; import org.jabsorb.ng.serializer.impl.SetSerializer; import org.jabsorb.ng.serializer.impl.StringSerializer; import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; import org.json.JSONTokener; /** * This class is the public entry point to the serialization code and provides * methods for marshalling Java objects into JSON objects and unmarshalling JSON * objects into Java objects. */ public class JSONSerializer implements Serializable { /** * Special token Object to indicate the fact that the given object being * marshalled is a duplicate or circular reference and so it should not be * placed into the json stream. */ public static final Object CIRC_REF_OR_DUPLICATE = new Object(); /** * The list of class types that are considered primitives that should not be * fixed up when fixupDuplicatePrimitives is false. */ protected static Class<?>[] duplicatePrimitiveTypes = { String.class, Integer.class, Boolean.class, Long.class, Byte.class, Double.class, Float.class, Short.class, Enum.class }; /** * The logger for this class */ private static final ILogger log = LoggerFactory.getLogger(JSONSerializer.class); /** * Unique serialisation id. */ private static final long serialVersionUID = 2; /** * Are FixUps are generated to handle circular references found during * marshalling? If false, an exception is thrown if a circular reference is * found during serialization. */ private boolean fixupCircRefs = false; /** * Are FixUps are generated for primitive objects (classes of type String, * Boolean, Integer, Boolean, Long, Byte, Double, Float and Short) This flag * will have no effect if fixupDuplicates is false. */ private boolean fixupDuplicatePrimitives = false; /** * Are FixUps are generated for duplicate objects found during marshalling? * If false, the duplicates are re-serialized. */ private boolean fixupDuplicates = false; /** * Should serializers defined in this object include the fully qualified * class name of objects being serialized? This can be helpful when * unmarshalling, though if not needed can be left out in favor of increased * performance and smaller size of marshalled String. */ private boolean marshallClassHints = true; /** * Should attributes will null values still be included in the serialized * JSON object. */ private boolean marshallNullAttributes = true; /** * key: Class, value: Serializer */ private transient Map<Class<?>, Serializer> serializableMap = null; /** * List for reverse registration order search */ private final List<Serializer> serializerList = new ArrayList<Serializer>(); /** * Key: Serializer */ private final Set<Serializer> serializerSet = new HashSet<Serializer>(); /** * Convert a string in JSON format into Java objects. * * @param jsonString * The JSON format string. * @return An object (or tree of objects) representing the data in the JSON * format string. * @throws UnmarshallException * If unmarshalling fails */ public Object fromJSON(final String jsonString) throws UnmarshallException { final ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader(); try { // Force the class loader Thread.currentThread().setContextClassLoader(getClass().getClassLoader()); final JSONTokener tok = new JSONTokener(jsonString); Object json; try { json = tok.nextValue(); } catch (final JSONException e) { throw new UnmarshallException("couldn't parse JSON", e); } final SerializerState state = new SerializerState(); return unmarshall(state, null, json); } finally { // Reset the context class loader Thread.currentThread().setContextClassLoader(contextClassLoader); } } /** * Find the corresponding java Class type from json (as represented by a * JSONObject or JSONArray,) using the javaClass hinting mechanism. * <p/> * If the Object is a JSONObject, the simple javaClass property is looked * for. If it is a JSONArray then this method is invoked recursively on the * first element of the array. * <p/> * then the Class is returned as an array type for the type of class hinted * by the first Object in the array. * <p/> * If the object is neither a JSONObject or JSONArray, return the Class of * the object directly. (this implies a primitive type, such as String, * Integer or Boolean) * * @param o * a JSONObject or JSONArray object to get the Class type from * the javaClass hint. * @return the Class of javaClass hint found, or null if the passed in * Object is null, or the Class of the Object passed in, if that * object is not a JSONArray or JSONObject. * @throws UnmarshallException * if javaClass hint was not found (except for null case or * primitive object case), or the javaClass hint is not a valid * java class. * <p/> * todo: the name of this method is a bit misleading because it * doesn't actually get the class from todo: the javaClass hint * if the type of Object passed in is not JSONObject|JSONArray. */ private Class<?> getClassFromHint(final Object o) throws UnmarshallException { if (o == null) { return null; } if (o instanceof JSONObject) { String className = "(unknown)"; try { className = ((JSONObject) o).getString("javaClass"); return Class.forName(className); // return classLoader.loadClass(className); } catch (final Exception e) { throw new UnmarshallException("Class specified in javaClass hint not found: " + className, e); } } if (o instanceof JSONArray) { final JSONArray arr = (JSONArray) o; if (arr.length() == 0) { // Use an empty list if the type is unknown // return ArrayList.class; return Object[].class; // throw new UnmarshallException("no type for empty array"); } // return type of first element Class<?> compClazz; try { compClazz = getClassFromHint(arr.get(0)); } catch (final JSONException e) { throw (NoSuchElementException) new NoSuchElementException(e.getMessage()).initCause(e); } try { if (compClazz.isArray()) { return Class.forName("[" + compClazz.getName()); // return classLoader.loadClass("[" + compClazz.getName()); } return Class.forName("[L" + compClazz.getName() + ";"); // return classLoader.loadClass("[L" + compClazz.getName() + // ";"); } catch (final ClassNotFoundException e) { System.err.println("PROBLEM GETTING ARRAY TYPE:"); e.printStackTrace(); System.out.println("Array = " + arr); System.out.println("CompoClazz = " + compClazz.getName()); throw new UnmarshallException("problem getting array type", e); } } return o.getClass(); } /** * Get the fixupCircRefs flag. If true, FixUps are generated to handle * circular references found during marshalling. If false, an exception is * thrown if a circular reference is found during serialization. * * @return the fixupCircRefs flag. */ public boolean getFixupCircRefs() { return fixupCircRefs; } /** * Get the fixupDuplicatePrimitives flag. If true (and fixupDuplicates is * also true), FixUps are generated for duplicate primitive objects found * during marshalling. If false, the duplicates are re-serialized. * * @return the fixupDuplicatePrimitives flag. */ public boolean getFixupDuplicatePrimitives() { return fixupDuplicatePrimitives; } /** * Get the fixupDuplicates flag. If true, FixUps are generated for duplicate * objects found during marshalling. If false, the duplicates are * re-serialized. * * @return the fixupDuplicates flag. */ public boolean getFixupDuplicates() { return fixupDuplicates; } /** * Should serializers defined in this object include the fully qualified * class name of objects being serialized? This can be helpful when * unmarshalling, though if not needed can be left out in favor of increased * performance and smaller size of marshalled String. Default is true. * * @return whether Java Class hints are included in the serialised JSON * objects */ public boolean getMarshallClassHints() { return marshallClassHints; } /** * Returns true if attributes will null values should still be included in * the serialized JSON object. Defaults to true. Set to false for * performance gains and small JSON serialized size. Useful because null and * undefined for JSON object attributes is virtually the same thing. * * @return boolean value as to whether null attributes will be in the * serialized JSON objects */ public boolean getMarshallNullAttributes() { return marshallNullAttributes; } /** * Find the serializer for the given Java type and/or JSON type. * * @param clazz * The Java class to lookup. * @param jsoClazz * The JSON class type to lookup (may be null in the marshalling * case in which case only the class is used to lookup the * serializer). * @return The found Serializer for the types specified or null if none * could be found. */ private Serializer getSerializer(final Class<?> clazz, final Class<?> jsoClazz) { if (log.isDebugEnabled()) { log.info("getSerializer", "looking for serializer - java:" + (clazz == null ? "null" : clazz.getName()) + " json:" + (jsoClazz == null ? "null" : jsoClazz.getName())); } synchronized (serializerSet) { Serializer s = serializableMap.get(clazz); if (s != null && s.canSerialize(clazz, jsoClazz)) { if (log.isDebugEnabled()) { log.info("getSerializer", "direct match serializer " + s.getClass().getName()); } return s; } final Iterator<Serializer> i = serializerList.iterator(); while (i.hasNext()) { s = i.next(); if (s.canSerialize(clazz, jsoClazz)) { if (log.isDebugEnabled()) { log.info("getSerializer", "search found serializer " + s.getClass().getName()); } return s; } } } return null; } /** * Determine if this serializer considers the given Object to be a primitive * wrapper type Object. This is used to determine which types of Objects * should be fixed up as duplicates if the fixupDuplicatePrimitives flag is * false. * * @param o * Object to test for primitive. */ public boolean isPrimitive(final Object o) { if (o == null) { return true; // extra safety check- null is considered primitive too } final Class<?> c = o.getClass(); for (int i = 0, j = duplicatePrimitiveTypes.length; i < j; i++) { if (duplicatePrimitiveTypes[i] == c) { return true; } } return false; } /** * Marshall java into an equivalent json representation (JSONObject or * JSONArray.) * <p/> * This involves finding the correct Serializer for the class of the given * java object and then invoking it to marshall the java object into json. * <p/> * The Serializer will invoke this method recursively while marshalling * complex object graphs. * * @param state * can be used by the underlying Serializer objects to hold state * while marshalling. * * @param parent * parent object of the object being converted. this can be null * if it's the root object being converted. * @param java * java object to convert into json. * * @param ref * reference within the parent's point of view of the object * being serialized. this will be a String for JSONObjects and an * Integer for JSONArrays. * * @return the JSONObject or JSONArray (or primitive object) containing the * json for the marshalled java object or the special token Object, * JSONSerializer.CIRC_REF_OR_DUP to indicate to the caller that the * given Object has already been serialized and so therefore the * result should be ignored. * * @throws MarshallException * if there is a problem marshalling java to json. */ public Object marshall(final SerializerState state, final Object parent, final Object java, final Object ref) throws MarshallException { if (java == null) { if (log.isDebugEnabled()) { log.debug("marshall", "marshall null"); } return JSONObject.NULL; } // check for duplicate objects or circular references final ProcessedObject p = state.getProcessedObject(java); // if this object hasn't been seen before, mark it as seen and continue // forth if (p == null) { state.push(parent, java, ref); } else { // todo: make test cases to explicitly handle all 4 combinations of // the 2 option // todo: settings (both on the client and server) // handle throwing of circular reference exception and/or // serializing duplicates, depending // on the options set in the serializer! final boolean foundCircRef = state.isAncestor(p, parent); // throw an exception if a circular reference found, and the // serializer option is not set to fixup these circular references if (!fixupCircRefs && foundCircRef) { throw new MarshallException("Circular Reference"); } // if its a duplicate only, and we aren't fixing up duplicates or if // it is a primitive, and fixing up of primitives is not allowed // then // re-serialize the object into the json. if (!foundCircRef && (!fixupDuplicates || (!fixupDuplicatePrimitives && isPrimitive(java)))) { // todo: if a duplicate is being reserialized... it will // overwrite the original location of the // todo: first one found... need to think about the // ramifications of this -- optimally, circ refs found // todo: underneath duplicates need to point to the "original" // one found, but they also need to be fixed // todo: up to the correct location, of course. state.push(parent, java, ref); } else { // generate a fix up entry for the duplicate/circular reference state.addFixUp(p.getLocation(), ref); return CIRC_REF_OR_DUPLICATE; } } try { if (log.isDebugEnabled()) { log.debug("marshall", "marshall class " + java.getClass().getName()); } final Serializer s = getSerializer(java.getClass(), null); if (s != null) { return s.marshall(state, parent, java); } throw new MarshallException("can't marshall " + java.getClass().getName()); } finally { state.pop(); } } /** * Reads an object, serialising each This is used by the java serialization * logic. * * @param in * The stream to take an object to serialise * @throws java.io.IOException * if the object can't be read from the stream * @throws ClassNotFoundException * If a class cannot be found for the object to be read * * @see java.io.Serializable */ private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { in.defaultReadObject(); serializableMap = new HashMap<Class<?>, Serializer>(); final Iterator<Serializer> i = serializerList.iterator(); while (i.hasNext()) { final Serializer s = i.next(); final Class<?> classes[] = s.getSerializableClasses(); for (int j = 0; j < classes.length; j++) { serializableMap.put(classes[j], s); } } } /** * Register all of the provided standard serializers. * * @throws Exception * If a serialiser has already been registered for a class. * * TODO: Should this be thrown: This can only happen if there is * an internal problem with the code */ public void registerDefaultSerializers() throws Exception { // the order of registration is important: // when trying to marshall java objects into json, first, // a direct match (by Class) is looked for in the serializeableMap // if a direct match is not found, all serializers are // searched in the reverse order that they were registered here (via the // serializerList) // for the first serializer that canSerialize the java class type. registerSerializer(new RawJSONArraySerializer()); registerSerializer(new RawJSONObjectSerializer()); registerSerializer(new BeanSerializer()); registerSerializer(new EnumSerializer()); registerSerializer(new ArraySerializer()); registerSerializer(new DictionarySerializer()); registerSerializer(new MapSerializer()); registerSerializer(new SetSerializer()); registerSerializer(new ListSerializer()); registerSerializer(new DateSerializer()); registerSerializer(new StringSerializer()); registerSerializer(new NumberSerializer()); registerSerializer(new BooleanSerializer()); registerSerializer(new PrimitiveSerializer()); } /** * Register a new type specific serializer. The order of registration is * important. More specific serializers should be added after less specific * serializers. This is because when the JSONSerializer is trying to find a * serializer, if it can't find the serializer by a direct match, it will * search for a serializer in the reverse order that they were registered. * * @param s * A class implementing the Serializer interface (usually derived * from AbstractSerializer). * * @throws Exception * If a serialiser has already been registered for a class. */ public void registerSerializer(final Serializer s) throws Exception { final Class<?> classes[] = s.getSerializableClasses(); Serializer exists; synchronized (serializerSet) { if (serializableMap == null) { serializableMap = new HashMap<Class<?>, Serializer>(); } for (int i = 0; i < classes.length; i++) { exists = serializableMap.get(classes[i]); if (exists != null && exists.getClass() != s.getClass()) { throw new Exception("different serializer already registered for " + classes[i].getName()); } } if (!serializerSet.contains(s)) { if (log.isDebugEnabled()) { log.debug("registerSerializer", "registered serializer " + s.getClass().getName()); } s.setOwner(this); serializerSet.add(s); serializerList.add(0, s); for (int j = 0; j < classes.length; j++) { serializableMap.put(classes[j], s); } } } } /** * Set the fixupCircRefs flag. If true, FixUps are generated to handle * circular references found during marshalling. If false, an exception is * thrown if a circular reference is found during serialization. * * @param fixupCircRefs * the fixupCircRefs flag. */ public void setFixupCircRefs(final boolean fixupCircRefs) { this.fixupCircRefs = fixupCircRefs; } /** * Set the fixupDuplicatePrimitives flag. If true (and fixupDuplicates is * also true), FixUps are generated for duplicate primitive objects found * during marshalling. If false, the duplicates are re-serialized. * * @param fixupDuplicatePrimitives * the fixupDuplicatePrimitives flag. */ public void setFixupDuplicatePrimitives(final boolean fixupDuplicatePrimitives) { this.fixupDuplicatePrimitives = fixupDuplicatePrimitives; } /** * Set the fixupDuplicates flag. If true, FixUps are generated for duplicate * objects found during marshalling. If false, the duplicates are * re-serialized. * * @param fixupDuplicates * the fixupDuplicates flag. */ public void setFixupDuplicates(final boolean fixupDuplicates) { this.fixupDuplicates = fixupDuplicates; } /** * Should serializers defined in this object include the fully qualified * class name of objects being serialized? This can be helpful when * unmarshalling, though if not needed can be left out in favor of increased * performance and smaller size of marshalled String. Default is true. * * @param marshallClassHints * flag to enable/disable inclusion of Java class hints in the * serialized JSON objects */ public void setMarshallClassHints(final boolean marshallClassHints) { this.marshallClassHints = marshallClassHints; } /** * Returns true if attributes will null values should still be included in * the serialized JSON object. Defaults to true. Set to false for * performance gains and small JSON serialized size. Useful because null and * undefined for JSON object attributes is virtually the same thing. * * @param marshallNullAttributes * flag to enable/disable marshalling of null attributes in the * serialized JSON objects */ public void setMarshallNullAttributes(final boolean marshallNullAttributes) { this.marshallNullAttributes = marshallNullAttributes; } /** * Convert a Java objects (or tree of Java objects) into a string in JSON * format. Note that this method will remove any circular references / * duplicates and not handle the potential fixups that could be generated. * (unless duplicates/circular references are turned off. * * todo: have some way to transmit the fixups back to the caller of this * method. * * @param obj * the object to be converted to JSON. * @return the JSON format string representing the data in the the Java * object. * @throws MarshallException * If marshalling fails. */ public String toJSON(final Object obj) throws MarshallException { final SerializerState state = new SerializerState(); // todo: what do we do about fix ups here? final Object json = marshall(state, null, obj, "result"); // todo: fixups will be in state.getFixUps() if someone wants to do // something with them... return json.toString(); } /** * <p> * Determine if a given JSON object matches a given class type, and to what * degree it matches. An ObjectMatch instance is returned which contains a * number indicating the number of fields that did not match. Therefore when * a given parameter could potentially match in more that one way, this is a * metric to compare these ObjectMatches to determine which one matches more * closely. * </p> * <p> * This is only used when there are overloaded method names that are being * called from JSON-RPC to determine which call signature the method call * matches most closely and therefore which method is the intended target * method to call. * </p> * * @param state * used by the underlying Serializer objects to hold state while * unmarshalling for detecting circular references and * duplicates. * * @param clazz * optional java class to unmarshall to- if set to null then it * will be looked for via the javaClass hinting mechanism. * * @param json * JSONObject or JSONArray or primitive Object wrapper that * contains the json to unmarshall. * * @return an ObjectMatch indicating the degree to which the object matched * the class, * @throws UnmarshallException * if getClassFromHint() fails */ public ObjectMatch tryUnmarshall(final SerializerState state, Class<?> clazz, final Object json) throws UnmarshallException { // check for duplicate objects or circular references ProcessedObject p = state.getProcessedObject(json); // if this object hasn't been seen before, mark it as seen and continue // forth if (p == null) { p = state.store(json); } else { // get original serialized version // to recreate circular reference / duplicate object on the java // side return (ObjectMatch) p.getSerialized(); } /* * If we have a JSON object class hint that is a sub class of the * signature 'clazz', then override 'clazz' with the hint class. */ if (clazz != null && json instanceof JSONObject && ((JSONObject) json).has("javaClass") && clazz.isAssignableFrom(getClassFromHint(json))) { clazz = getClassFromHint(json); } if (clazz == null) { clazz = getClassFromHint(json); } if (clazz == null) { throw new UnmarshallException("no class hint"); } if (json == null || json == JSONObject.NULL) { if (!clazz.isPrimitive()) { return ObjectMatch.NULL; } throw new UnmarshallException("can't assign null primitive"); } final Serializer s = getSerializer(clazz, json.getClass()); if (s != null) { return s.tryUnmarshall(state, clazz, json); } // As a last resort, we check if the object is in fact an instance of // the // desired class. This will typically happen when the parameter is of // type java.lang.Object and the passed object is a String or an Integer // that is passed verbatim by JSON if (clazz.isInstance(json)) { return ObjectMatch.SIMILAR; } throw new UnmarshallException("no match"); } /** * Unmarshall json into an equivalent java object. * <p/> * This involves finding the correct Serializer to use and then delegating * to that Serializer to unmarshall for us. This method will be invoked * recursively as Serializers unmarshall complex object graphs. * * @param state * used by the underlying Serializer objects to hold state while * unmarshalling for detecting circular references and * duplicates. * * @param clazz * optional java class to unmarshall to- if set to null then it * will be looked for via the javaClass hinting mechanism. * * @param json * JSONObject or JSONArray or primitive Object wrapper that * contains the json to unmarshall. * * @return the java object representing the json that was unmarshalled. * * @throws UnmarshallException * if there is a problem unmarshalling json to java. */ public Object unmarshall(final SerializerState state, Class<?> clazz, final Object json) throws UnmarshallException { // check for duplicate objects or circular references ProcessedObject p = state.getProcessedObject(json); // if this object hasn't been seen before, mark it as seen and continue // forth if (p == null) { p = state.store(json); } else { // get original serialized version // to recreate circular reference / duplicate object on the java // side return p.getSerialized(); } // If we have a JSON object class hint that is a sub class of the // signature 'clazz', then override 'clazz' with the hint class. if (clazz != null && json instanceof JSONObject && ((JSONObject) json).has("javaClass") && clazz.isAssignableFrom(getClassFromHint(json))) { clazz = getClassFromHint(json); } // if no clazz type was passed in, look for the javaClass hint if (clazz == null) { clazz = getClassFromHint(json); } if (clazz == null) { throw new UnmarshallException("no class hint"); } if (JSONObject.NULL.equals(json)) { if (!clazz.isPrimitive()) { return null; } throw new UnmarshallException("can't assign null primitive"); } final Class<?> jsonClass = json.getClass(); final Serializer s = getSerializer(clazz, jsonClass); if (s != null) { return s.unmarshall(state, clazz, json); } // As a last resort, we check if the object is in fact an instance of // the // desired class. This will typically happen when the parameter is of // type java.lang.Object and the passed object is a String or an Integer // that is passed verbatim by JSON if (clazz.isInstance(json)) { return json; } throw new UnmarshallException("no serializer found that can unmarshall " + (jsonClass != null ? jsonClass.getName() : "null") + " to " + clazz.getName()); } }