com.mxgraph.io

## Class mxObjectCodec

- java.lang.Object
- - com.mxgraph.io.mxObjectCodec

- Direct Known Subclasses:
    mxCellCodec, mxChildChangeCodec, mxGenericChangeCodec, mxModelCodec, mxRootChangeCodec, mxStylesheetCodec, mxTerminalChangeCodec

      public class mxObjectCodec
      extends java.lang.Object

  Generic codec for Java objects. See below for a detailed description of the encoding/decoding scheme. Note: Since booleans are numbers in JavaScript, all boolean values are encoded into 1 for true and 0 for false.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.Map<java.lang.String,java.lang.reflect.Method>` | `accessors` Caches accessors for the given method names.
    `protected java.util.Set<java.lang.String>` | `exclude` Array containing the variable names that should be ignored by the codec.
    `protected java.util.Map<java.lang.Class,java.util.Map<java.lang.String,java.lang.reflect.Field>>` | `fields` Caches fields for faster access.
    `protected java.util.Set<java.lang.String>` | `idrefs` Array containing the variable names that should be turned into or converted from references.
    `protected java.util.Map<java.lang.String,java.lang.String>` | `mapping` Maps from from fieldnames to XML attribute names.
    `protected java.util.Map<java.lang.String,java.lang.String>` | `reverse` Maps from from XML attribute names to fieldnames.
    `protected java.lang.Object` | `template` Holds the template object associated with this codec.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `mxObjectCodec(java.lang.Object template)` Constructs a new codec for the specified template object.
    `mxObjectCodec(java.lang.Object template, java.lang.String[] exclude, java.lang.String[] idrefs, java.util.Map<java.lang.String,java.lang.String> mapping)` Constructs a new codec for the specified template object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addObjectValue(java.lang.Object obj, java.lang.String fieldname, java.lang.Object value, java.lang.Object template)` Sets the decoded child node as a value of the given object.
    `java.lang.Object` | `afterDecode(mxCodec dec, org.w3c.dom.Node node, java.lang.Object obj)` Hook for subclassers to post-process the object after decoding.
    `org.w3c.dom.Node` | `afterEncode(mxCodec enc, java.lang.Object obj, org.w3c.dom.Node node)` Hook for subclassers to post-process the node for the given object after encoding and return the post-processed node.
    `org.w3c.dom.Node` | `beforeDecode(mxCodec dec, org.w3c.dom.Node node, java.lang.Object obj)` Hook for subclassers to pre-process the node for the specified object and return the node to be used for further processing by `decode(mxCodec, Node)`.
    `java.lang.Object` | `beforeEncode(mxCodec enc, java.lang.Object obj, org.w3c.dom.Node node)` Hook for subclassers to pre-process the object before encoding.
    `protected java.lang.Object` | `cloneTemplate(org.w3c.dom.Node node)` Returns a new instance of the template object for representing the given node.
    `protected java.lang.Object` | `convertValueFromXml(java.lang.Class<?> type, java.lang.Object value)` Converts XML attribute values to object of the given type.
    `protected java.lang.Object` | `convertValueToXml(java.lang.Object value)` Converts true to "1" and false to "0".
    `java.lang.Object` | `decode(mxCodec dec, org.w3c.dom.Node node)` Parses the given node into the object or returns a new object representing the given node.
    `java.lang.Object` | `decode(mxCodec dec, org.w3c.dom.Node node, java.lang.Object into)` Parses the given node into the object or returns a new object representing the given node.
    `protected void` | `decodeAttribute(mxCodec dec, org.w3c.dom.Node attr, java.lang.Object obj)` Reads the given attribute into the specified object.
    `protected void` | `decodeAttributes(mxCodec dec, org.w3c.dom.Node node, java.lang.Object obj)` Decodes all attributes of the given node using decodeAttribute.
    `protected void` | `decodeChild(mxCodec dec, org.w3c.dom.Node child, java.lang.Object obj)` Reads the specified child into the given object.
    `protected void` | `decodeChildren(mxCodec dec, org.w3c.dom.Node node, java.lang.Object obj)` Decodec all children of the given node using decodeChild.
    `protected void` | `decodeNode(mxCodec dec, org.w3c.dom.Node node, java.lang.Object obj)` Calls decodeAttributes and decodeChildren for the given node.
    `org.w3c.dom.Node` | `encode(mxCodec enc, java.lang.Object obj)` Encodes the specified object and returns a node representing then given object.
    `protected void` | `encodeElements(mxCodec enc, java.lang.Object obj, org.w3c.dom.Node node)` Encodes the child objects of arrays, maps and collections.
    `protected void` | `encodeFields(mxCodec enc, java.lang.Object obj, org.w3c.dom.Node node)` Encodes the declared fields of the given object into the given node.
    `protected void` | `encodeObject(mxCodec enc, java.lang.Object obj, org.w3c.dom.Node node)` Encodes the value of each member in then given obj into the given node using `encodeFields(mxCodec, Object, Node)` and `encodeElements(mxCodec, Object, Node)`.
    `protected void` | `encodeValue(mxCodec enc, java.lang.Object obj, java.lang.String fieldname, java.lang.Object value, org.w3c.dom.Node node)` Converts the given value according to the mappings and id-refs in this codec and uses `writeAttribute(mxCodec, Object, String, Object, Node)` to write the attribute into the given node.
    `protected java.lang.reflect.Method` | `getAccessor(java.lang.Object obj, java.lang.reflect.Field field, boolean isGetter)` Returns the accessor (getter, setter) for the specified field.
    `protected java.lang.String` | `getAttributeName(java.lang.String fieldname)` Returns the XML node attribute name for the given Java field name.
    `protected java.lang.reflect.Field` | `getField(java.lang.Object obj, java.lang.String fieldname)` Returns the field with the specified name.
    `protected java.lang.String` | `getFieldName(java.lang.String attributename)` Returns the Java field name for the given XML attribute name.
    `protected java.lang.Object` | `getFieldTemplate(java.lang.Object obj, java.lang.String fieldname, org.w3c.dom.Node child)` Returns the template instance for the given field.
    `protected java.lang.Object` | `getFieldValue(java.lang.Object obj, java.lang.String fieldname)` Returns the value of the field with the specified name in the specified object instance.
    `protected java.lang.Object` | `getFieldValueWithAccessor(java.lang.Object obj, java.lang.reflect.Field field)` Returns the value of the field using the accessor for the field if one exists.
    `protected java.lang.reflect.Method` | `getMethod(java.lang.Object obj, java.lang.String methodname, java.lang.Class[] params)` Returns the method with the specified signature.
    `java.lang.String` | `getName()` Returns the name used for the nodenames and lookup of the codec when classes are encoded and nodes are decoded.
    `java.lang.Object` | `getTemplate()` Returns the template object associated with this codec.
    `boolean` | `isExcluded(java.lang.Object obj, java.lang.String attr, java.lang.Object value, boolean write)` Returns true if the given attribute is to be ignored by the codec.
    `protected boolean` | `isPrimitiveValue(java.lang.Object value)` Returns true if the given object is a primitive value.
    `boolean` | `isReference(java.lang.Object obj, java.lang.String attr, java.lang.Object value, boolean isWrite)` Returns true if the given fieldname is to be treated as a textual reference (ID).
    `boolean` | `processInclude(mxCodec dec, org.w3c.dom.Node node, java.lang.Object into)` Returns true if the given node is an include directive and executes the include by decoding the XML document.
    `protected void` | `setFieldValue(java.lang.Object obj, java.lang.String fieldname, java.lang.Object value)` Sets the value of the field with the specified name in the specified object instance.
    `protected void` | `setFieldValueWithAccessor(java.lang.Object obj, java.lang.reflect.Field field, java.lang.Object value)` Sets the value of the given field using the accessor if one exists.
    `protected void` | `writeAttribute(mxCodec enc, java.lang.Object obj, java.lang.String attr, java.lang.Object value, org.w3c.dom.Node node)` Writes the given value into node using writePrimitiveAttribute or writeComplexAttribute depending on the type of the value.
    `protected void` | `writeComplexAttribute(mxCodec enc, java.lang.Object obj, java.lang.String attr, java.lang.Object value, org.w3c.dom.Node node)` Writes the given value as a child node of the given node.
    `protected void` | `writePrimitiveAttribute(mxCodec enc, java.lang.Object obj, java.lang.String attr, java.lang.Object value, org.w3c.dom.Node node)` Writes the given value as an attribute of the given node.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### template

          protected java.lang.Object template

      Holds the template object associated with this codec.

    - #### exclude

          protected java.util.Set<java.lang.String> exclude

      Array containing the variable names that should be ignored by the codec.

    - #### idrefs

          protected java.util.Set<java.lang.String> idrefs

      Array containing the variable names that should be turned into or converted from references. See and .

    - #### mapping

          protected java.util.Map<java.lang.String,java.lang.String> mapping

      Maps from from fieldnames to XML attribute names.

    - #### reverse

          protected java.util.Map<java.lang.String,java.lang.String> reverse

      Maps from from XML attribute names to fieldnames.

    - #### accessors

          protected java.util.Map<java.lang.String,java.lang.reflect.Method> accessors

      Caches accessors for the given method names.

    - #### fields

          protected java.util.Map<java.lang.Class,java.util.Map<java.lang.String,java.lang.reflect.Field>> fields

      Caches fields for faster access.

  - ### Constructor Detail

    - #### mxObjectCodec

          public mxObjectCodec(java.lang.Object template)

      Constructs a new codec for the specified template object.

    - #### mxObjectCodec

          public mxObjectCodec(java.lang.Object template,
                       java.lang.String[] exclude,
                       java.lang.String[] idrefs,
                       java.util.Map<java.lang.String,java.lang.String> mapping)

      Constructs a new codec for the specified template object. The variables in the optional exclude array are ignored by the codec. Variables in the optional idrefs array are turned into references in the XML. The optional mapping may be used to map from variable names to XML attributes. The argument is created as follows:
      Parameters:
        `template` - Prototypical instance of the object to be encoded/decoded.
        `exclude` - Optional array of fieldnames to be ignored.
        `idrefs` - Optional array of fieldnames to be converted to/from references.
        `mapping` - Optional mapping from field- to attributenames.

  - ### Method Detail

    - #### getName

          public java.lang.String getName()

      Returns the name used for the nodenames and lookup of the codec when classes are encoded and nodes are decoded. For classes to work with this the codec registry automatically adds an alias for the classname if that is different than what this returns. The default implementation returns the classname of the template class. Here is an example on how to use this for renaming mxCell nodes: `mxCodecRegistry.register(new mxCellCodec() { public String getName() { return "anotherName"; } });`

    - #### getTemplate

          public java.lang.Object getTemplate()

      Returns the template object associated with this codec.
      Returns:
        Returns the template object.

    - #### cloneTemplate

          protected java.lang.Object cloneTemplate(org.w3c.dom.Node node)

      Returns a new instance of the template object for representing the given node.
      Parameters:
        `node` - XML node that the object is going to represent.
      Returns:
        Returns a new template instance.

    - #### isExcluded

          public boolean isExcluded(java.lang.Object obj,
                           java.lang.String attr,
                           java.lang.Object value,
                           boolean write)

      Returns true if the given attribute is to be ignored by the codec. This implementation returns true if the given fieldname is in `exclude`.
      Parameters:
        `obj` - Object instance that contains the field.
        `attr` - Fieldname of the field.
        `value` - Value of the field.
        `write` - Boolean indicating if the field is being encoded or decoded. write is true if the field is being encoded, else it is being decoded.
      Returns:
        Returns true if the given attribute should be ignored.

    - #### isReference

          public boolean isReference(java.lang.Object obj,
                            java.lang.String attr,
                            java.lang.Object value,
                            boolean isWrite)

      Returns true if the given fieldname is to be treated as a textual reference (ID). This implementation returns true if the given fieldname is in `idrefs`.
      Parameters:
        `obj` - Object instance that contains the field.
        `attr` - Fieldname of the field.
        `value` - Value of the field.
        `isWrite` - Boolean indicating if the field is being encoded or decoded. isWrite is true if the field is being encoded, else it is being decoded.
      Returns:
        Returns true if the given attribute should be handled as a reference.

    - #### encode

          public org.w3c.dom.Node encode(mxCodec enc,
                                java.lang.Object obj)

      Encodes the specified object and returns a node representing then given object. Calls beforeEncode after creating the node and afterEncode with the resulting node after processing. Enc is a reference to the calling encoder. It is used to encode complex objects and create references. This implementation encodes all variables of an object according to the following rules:
      - If the variable name is in `exclude` then it is ignored.
      - If the variable name is in `idrefs` then `mxCodec.getId(Object)` is used to replace the object with its ID.
      - The variable name is mapped using `mapping`.
      - If obj is an array and the variable name is numeric (ie. an index) then it is not encoded.
      - If the value is an object, then the codec is used to create a child node with the variable name encoded into the "as" attribute.
      - Else, if `mxCodec.isEncodeDefaults()` is true or the value differs from the template value, then ...
        - ... if obj is not an array, then the value is mapped to an attribute.
        - ... else if obj is an array, the value is mapped to an add child with a value attribute or a text child node, if the value is a function.
      If no ID exists for a variable in `idrefs` or if an object cannot be encoded, a warning is printed to System.err.
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object to be encoded.
      Returns:
        Returns the resulting XML node that represents the given object.

    - #### encodeObject

          protected void encodeObject(mxCodec enc,
                          java.lang.Object obj,
                          org.w3c.dom.Node node)

      Encodes the value of each member in then given obj into the given node using `encodeFields(mxCodec, Object, Node)` and `encodeElements(mxCodec, Object, Node)`.
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object to be encoded.
        `node` - XML node that contains the encoded object.

    - #### encodeFields

          protected void encodeFields(mxCodec enc,
                          java.lang.Object obj,
                          org.w3c.dom.Node node)

      Encodes the declared fields of the given object into the given node.
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object whose fields should be encoded.
        `node` - XML node that contains the encoded object.

    - #### encodeElements

          protected void encodeElements(mxCodec enc,
                            java.lang.Object obj,
                            org.w3c.dom.Node node)

      Encodes the child objects of arrays, maps and collections.
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object whose child objects should be encoded.
        `node` - XML node that contains the encoded object.

    - #### encodeValue

          protected void encodeValue(mxCodec enc,
                         java.lang.Object obj,
                         java.lang.String fieldname,
                         java.lang.Object value,
                         org.w3c.dom.Node node)

      Converts the given value according to the mappings and id-refs in this codec and uses `writeAttribute(mxCodec, Object, String, Object, Node)` to write the attribute into the given node.
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object whose field is going to be encoded.
        `fieldname` - Name if the field to be encoded.
        `value` - Value of the property to be encoded.
        `node` - XML node that contains the encoded object.

    - #### isPrimitiveValue

          protected boolean isPrimitiveValue(java.lang.Object value)

      Returns true if the given object is a primitive value.
      Parameters:
        `value` - Object that should be checked.
      Returns:
        Returns true if the given object is a primitive value.

    - #### writeAttribute

          protected void writeAttribute(mxCodec enc,
                            java.lang.Object obj,
                            java.lang.String attr,
                            java.lang.Object value,
                            org.w3c.dom.Node node)

      Writes the given value into node using writePrimitiveAttribute or writeComplexAttribute depending on the type of the value.

    - #### writePrimitiveAttribute

          protected void writePrimitiveAttribute(mxCodec enc,
                                     java.lang.Object obj,
                                     java.lang.String attr,
                                     java.lang.Object value,
                                     org.w3c.dom.Node node)

      Writes the given value as an attribute of the given node.

    - #### writeComplexAttribute

          protected void writeComplexAttribute(mxCodec enc,
                                   java.lang.Object obj,
                                   java.lang.String attr,
                                   java.lang.Object value,
                                   org.w3c.dom.Node node)

      Writes the given value as a child node of the given node.

    - #### convertValueToXml

          protected java.lang.Object convertValueToXml(java.lang.Object value)

      Converts true to "1" and false to "0". All other values are ignored.

    - #### convertValueFromXml

          protected java.lang.Object convertValueFromXml(java.lang.Class<?> type,
                                             java.lang.Object value)

      Converts XML attribute values to object of the given type.

    - #### getAttributeName

          protected java.lang.String getAttributeName(java.lang.String fieldname)

      Returns the XML node attribute name for the given Java field name. That is, it returns the mapping of the field name.

    - #### getFieldName

          protected java.lang.String getFieldName(java.lang.String attributename)

      Returns the Java field name for the given XML attribute name. That is, it returns the reverse mapping of the attribute name.
      Parameters:
        `attributename` - The attribute name to be mapped.
      Returns:
        String that represents the mapped field name.

    - #### getField

          protected java.lang.reflect.Field getField(java.lang.Object obj,
                                         java.lang.String fieldname)

      Returns the field with the specified name.

    - #### getAccessor

          protected java.lang.reflect.Method getAccessor(java.lang.Object obj,
                                             java.lang.reflect.Field field,
                                             boolean isGetter)

      Returns the accessor (getter, setter) for the specified field.

    - #### getMethod

          protected java.lang.reflect.Method getMethod(java.lang.Object obj,
                                           java.lang.String methodname,
                                           java.lang.Class[] params)

      Returns the method with the specified signature.

    - #### getFieldValue

          protected java.lang.Object getFieldValue(java.lang.Object obj,
                                       java.lang.String fieldname)

      Returns the value of the field with the specified name in the specified object instance.

    - #### getFieldValueWithAccessor

          protected java.lang.Object getFieldValueWithAccessor(java.lang.Object obj,
                                                   java.lang.reflect.Field field)

      Returns the value of the field using the accessor for the field if one exists.

    - #### setFieldValue

          protected void setFieldValue(java.lang.Object obj,
                           java.lang.String fieldname,
                           java.lang.Object value)

      Sets the value of the field with the specified name in the specified object instance.

    - #### setFieldValueWithAccessor

          protected void setFieldValueWithAccessor(java.lang.Object obj,
                                       java.lang.reflect.Field field,
                                       java.lang.Object value)

      Sets the value of the given field using the accessor if one exists.

    - #### beforeEncode

          public java.lang.Object beforeEncode(mxCodec enc,
                                      java.lang.Object obj,
                                      org.w3c.dom.Node node)

      Hook for subclassers to pre-process the object before encoding. This returns the input object. The return value of this function is used in encode to perform the default encoding into the given node.
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object to be encoded.
        `node` - XML node to encode the object into.
      Returns:
        Returns the object to be encoded by the default encoding.

    - #### afterEncode

          public org.w3c.dom.Node afterEncode(mxCodec enc,
                                     java.lang.Object obj,
                                     org.w3c.dom.Node node)

      Hook for subclassers to post-process the node for the given object after encoding and return the post-processed node. This implementation returns the input node. The return value of this method is returned to the encoder from . Parameters:
      Parameters:
        `enc` - Codec that controls the encoding process.
        `obj` - Object to be encoded.
        `node` - XML node that represents the default encoding.
      Returns:
        Returns the resulting node of the encoding.

    - #### decode

          public java.lang.Object decode(mxCodec dec,
                                org.w3c.dom.Node node)

      Parses the given node into the object or returns a new object representing the given node.
      Parameters:
        `dec` - Codec that controls the encoding process.
        `node` - XML node to be decoded.
      Returns:
        Returns the resulting object that represents the given XML node.

    - #### decode

          public java.lang.Object decode(mxCodec dec,
                                org.w3c.dom.Node node,
                                java.lang.Object into)

      Parses the given node into the object or returns a new object representing the given node. Dec is a reference to the calling decoder. It is used to decode complex objects and resolve references. If a node has an id attribute then the object cache is checked for the object. If the object is not yet in the cache then it is constructed using the constructor of
      Parameters:
        `dec` - Codec that controls the encoding process.
        `node` - XML node to be decoded.
        `into` - Optional object to encode the node into.
      Returns:
        Returns the resulting object that represents the given XML node or the object given to the method as the into parameter.

    - #### decodeNode

          protected void decodeNode(mxCodec dec,
                        org.w3c.dom.Node node,
                        java.lang.Object obj)

      Calls decodeAttributes and decodeChildren for the given node.

    - #### decodeAttributes

          protected void decodeAttributes(mxCodec dec,
                              org.w3c.dom.Node node,
                              java.lang.Object obj)

      Decodes all attributes of the given node using decodeAttribute.

    - #### decodeAttribute

          protected void decodeAttribute(mxCodec dec,
                             org.w3c.dom.Node attr,
                             java.lang.Object obj)

      Reads the given attribute into the specified object.

    - #### decodeChildren

          protected void decodeChildren(mxCodec dec,
                            org.w3c.dom.Node node,
                            java.lang.Object obj)

      Decodec all children of the given node using decodeChild.

    - #### decodeChild

          protected void decodeChild(mxCodec dec,
                         org.w3c.dom.Node child,
                         java.lang.Object obj)

      Reads the specified child into the given object.

    - #### getFieldTemplate

          protected java.lang.Object getFieldTemplate(java.lang.Object obj,
                                          java.lang.String fieldname,
                                          org.w3c.dom.Node child)

      Returns the template instance for the given field. This returns the value of the field, null if the value is an array or an empty collection if the value is a collection. The value is then used to populate the field for a new instance. For strongly typed languages it may be required to override this to return the correct collection instance based on the encoded child.

    - #### addObjectValue

          protected void addObjectValue(java.lang.Object obj,
                            java.lang.String fieldname,
                            java.lang.Object value,
                            java.lang.Object template)

      Sets the decoded child node as a value of the given object. If the object is a map, then the value is added with the given fieldname as a key. If the fieldname is not empty, then setFieldValue is called or else, if the object is a collection, the value is added to the collection. For strongly typed languages it may be required to override this with the correct code to add an entry to an object.

    - #### processInclude

          public boolean processInclude(mxCodec dec,
                               org.w3c.dom.Node node,
                               java.lang.Object into)

      Returns true if the given node is an include directive and executes the include by decoding the XML document. Returns false if the given node is not an include directive.
      Parameters:
        `dec` - Codec that controls the encoding/decoding process.
        `node` - XML node to be checked.
        `into` - Optional object to pass-thru to the codec.
      Returns:
        Returns true if the given node was processed as an include.

    - #### beforeDecode

          public org.w3c.dom.Node beforeDecode(mxCodec dec,
                                      org.w3c.dom.Node node,
                                      java.lang.Object obj)

      Hook for subclassers to pre-process the node for the specified object and return the node to be used for further processing by `decode(mxCodec, Node)`. The object is created based on the template in the calling method and is never null. This implementation returns the input node. The return value of this function is used in `decode(mxCodec, Node)` to perform the default decoding into the given object.
      Parameters:
        `dec` - Codec that controls the decoding process.
        `node` - XML node to be decoded.
        `obj` - Object to encode the node into.
      Returns:
        Returns the node used for the default decoding.

    - #### afterDecode

          public java.lang.Object afterDecode(mxCodec dec,
                                     org.w3c.dom.Node node,
                                     java.lang.Object obj)

      Hook for subclassers to post-process the object after decoding. This implementation returns the given object without any changes. The return value of this method is returned to the decoder from `decode(mxCodec, Node)`.
      Parameters:
        `dec` - Codec that controls the decoding process.
        `node` - XML node to be decoded.
        `obj` - Object that represents the default decoding.
      Returns:
        Returns the result of the decoding process.

Copyright (c) 2010 Gaudenz Alder. All rights reserved.