Package software.amazon.smithy.model.node

Class NodeMapper

  • public final class NodeMapper
extends java.lang.Object
    Serializes and deserializes Smithy Node values to/from objects.

    This class does not serialize a Node value as a JSON string. It converts Java Object values to and from Node values. Use Node.printJson(Node) to serialize JSON strings from a Node value.

    When stable, we may add the ability to add custom serializers and deserializers. Until then, there is no way to customize the serialization and deserialization rules.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  NodeMapper.WhenMissing
      Specifies the behavior of the mapper when attempting to deserialize an unknown property.

    • Constructor Summary

      Constructors 
      Constructor Description
      NodeMapper()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <T> T deserialize​(Node value, java.lang.Class<T> into)
      Deserialize a Node value into an instance of T.
      <T extends java.util.Collection<?>,​U,​V extends java.util.Collection<? extends U>>
      V      		 deserializeCollection​(Node value, java.lang.Class<T> into, java.lang.Class<U> members)
      Deserialize a Node value into a Collection T of U members.
      <T> T deserializeInto​(Node value, T objectToMutate)
      Invokes setters on the given objectToMutate from the provided Node.
      <T extends java.util.Map<?,​?>,​U,​V extends java.util.Map<java.lang.String,​? extends U>>
      V      		 deserializeMap​(Node value, java.lang.Class<T> into, java.lang.Class<U> members)
      Deserialize a Node value into a Map T with String keys and U values.
      void disableFromNodeForClass​(java.lang.reflect.Type type)
      Disables the use of fromNode method for a specific class when deserializing the class.
      void disableToNodeForClass​(java.lang.reflect.Type type)
      Disables the use of the toNode method for a specific class when serializing the class as a POJO.
      void enableFromNodeForClass​(java.lang.reflect.Type type)
      Enables the use of the FromNode method for a specific class when deserializing the class.
      void enableToNodeForClass​(java.lang.reflect.Type type)
      Enables the use of the toNode method for a specific class when serializing the class as a POJO.
      java.util.Set<java.lang.reflect.Type> getDisableFromNode()
      Gets the set of classes where fromNode is disabled.
      java.util.Set<java.lang.reflect.Type> getDisableToNode()
      Gets the set of classes where toNode is disabled.
      boolean getOmitEmptyValues()
      Gets whether or not false, empty arrays, and empty objects are omitted from serialized POJOs.
      boolean getSerializeNullValues()  
      NodeMapper.WhenMissing getWhenMissingSetter()  
      Node serialize​(java.lang.Object object)
      Serializes the given object as a Node.
      void setOmitEmptyValues​(boolean omitEmptyValues)
      Gets whether or not false, empty arrays, and empty objects are omitted from serialized POJOs.
      void setSerializeNullValues​(boolean serializeNullValues)
      Specifies if null values returned from getters are serialized.
      void setWhenMissingSetter​(NodeMapper.WhenMissing whenMissing)
      Sets the behavior of the deserializer when a setting is missing.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • NodeMapper

        public NodeMapper()

    • Method Detail

      • setSerializeNullValues

        public void setSerializeNullValues​(boolean serializeNullValues)
        Specifies if null values returned from getters are serialized.
        Parameters:
        serializeNullValues - Set to true to serialize null values.

      • getSerializeNullValues

        public boolean getSerializeNullValues()
        Returns:
        Gets whether or not null values are serialized.

      • setWhenMissingSetter

        public void setWhenMissingSetter​(NodeMapper.WhenMissing whenMissing)
        Sets the behavior of the deserializer when a setting is missing.
        Parameters:
        whenMissing - Behavior when a property is not matched to a setter.

      • getWhenMissingSetter

        public NodeMapper.WhenMissing getWhenMissingSetter()
        Returns:
        Gets the behavior of the deserializer when a setting is missing.

      • disableToNodeForClass

        public void disableToNodeForClass​(java.lang.reflect.Type type)
        Disables the use of the toNode method for a specific class when serializing the class as a POJO.

        This method disables a specific concrete class and does not disable subclasses or implementations of an interface.

        This is useful when using the NodeMapper inside of a toNode implementation.

        Parameters:
        type - Class to disable the toNode method serialization for.

      • enableToNodeForClass

        public void enableToNodeForClass​(java.lang.reflect.Type type)
        Enables the use of the toNode method for a specific class when serializing the class as a POJO.
        Parameters:
        type - Class to enable the toNode method serialization for.

      • getDisableToNode

        public java.util.Set<java.lang.reflect.Type> getDisableToNode()
        Gets the set of classes where toNode is disabled.
        Returns:
        Returns the disabled classes.

      • disableFromNodeForClass

        public void disableFromNodeForClass​(java.lang.reflect.Type type)
        Disables the use of fromNode method for a specific class when deserializing the class.

        This method disables a specific concrete class and does not disable subclasses or implementations of an interface.

        This is useful when using the NodeMapper inside of a fromNode implementation.

        Parameters:
        type - Class to disable the fromNode method deserialization for.

      • enableFromNodeForClass

        public void enableFromNodeForClass​(java.lang.reflect.Type type)
        Enables the use of the FromNode method for a specific class when deserializing the class.
        Parameters:
        type - Class to enable the fromNode method deserialization for.

      • getDisableFromNode

        public java.util.Set<java.lang.reflect.Type> getDisableFromNode()
        Gets the set of classes where fromNode is disabled.
        Returns:
        Returns the disabled classes.

      • getOmitEmptyValues

        public boolean getOmitEmptyValues()
        Gets whether or not false, empty arrays, and empty objects are omitted from serialized POJOs.
        Returns:
        Returns true if empty arrays and POJOs returned from POJO getters are omitted.

      • setOmitEmptyValues

        public void setOmitEmptyValues​(boolean omitEmptyValues)
        Gets whether or not false, empty arrays, and empty objects are omitted from serialized POJOs.
        Parameters:
        omitEmptyValues - Set to true if false, empty arrays, and objects returned from POJO getters are omitted.

      • serialize

        public Node serialize​(java.lang.Object object)
        Serializes the given object as a Node.

        This method is able to serialize the following types in the given evaluation order:

        1. A null value is serialized as a NullNode if getSerializeNullValues() returns true.
        2. Instances of ToNode will return the result of calling ToNode.toNode().
        3. Instances of Optional will serialize a NullNode when the Optional is empty, or the result of serializing the value contained in the Optional when present.
        4. String value is serialized as a StringNode.
        5. Boolean value or boolean is serialized as a BooleanNode.
        6. Any instance of Number value is serialized as a NumberNode.
        7. The toString method is called when URL, URI, Pattern, and Path are serialized.
        8. A File is serialized by serializing the string value of File.toURI().
        9. Enum value is serialized as a StringNode by calling its toString method.
        10. ShapeId is serialized as a StringNode that contains the absolute shape ID.
        11. Any instance of a Map is supported as long as the key and value of the map are both supported types (note that Map keys must serialize as StringNode). A Map is converted to an ObjectNode.
        12. Any instance of a Iterable is supported as long as the value contained in the Iterable is a supported type. An Iterable is converted to an ArrayNode. An Iterable broadly covers many Java types, including Collection.
        13. Primitive arrays are converted to an ArrayNode if and only if the values contained in the array are one of the supported types supported by the serializer.
        14. Finally, an object is serialized using Bean style semantics; any public getter (get* or is* method with no arguments) is invoked and it's return value is put in the ObjectNode. Each property of the Bean recursively invokes the serializer and must be one of the supported types. Properties associated with a getter that are marked as transient are not serialized (where an "association" is defined as a class field with the same lowercase name as the suffix of the getter method). For example, given a method "getFoo", both "foo" and "Foo" are checked as associated property names.
        Parameters:
        object - Object to serialize.
        Returns:
        Returns the serialized Node.
        Throws:
        NodeSerializationException - on error.

      • deserialize

        public <T> T deserialize​(Node value,
                         java.lang.Class<T> into)
        Deserialize a Node value into an instance of T.

        This method can deserialize various kinds of values depending on the given node type and the target type:

        1. null
        2. String
        3. Primitive and boxed booleans
        4. Primitive and boxed Number types
        5. Lists and Sets of any support value
        6. Maps with String keys and values of any supported type
        7. Direct Node to Node conversions.
        8. Any object that has a public static fromNode method that accepts a Node and returns an instance of the object.
        9. Strings are deserialized to enums by finding the first enum value that has a toString method that matches the string value.
        10. Built-in support for URI, URL, Pattern, Path, and File
        11. When deserializing an object, any target object that provides a public static method named builder that returns an instance of SmithyBuilder is invoked, and the builder is then mutated using bean like setters (with an optional "set") prefix, until finally, the build method is called and its result is returned.
        12. When deserializing an object, the last thing tried is to find a public, zero-arg constructor, and then the object is mutated using bean-style setter conventions for each key-value pair.
        13. NodeMapper does not support non-static inner classes, classes with generic parameters, or generic arrays. Support for these may be added in the future.

        Objects with a public method named sourceLocation or setSourceLocation are invoked and provided the source location of the deserialized value.

        Type Parameters:
        T - Type of value to create.
        Parameters:
        value - Value to deserialize.
        into - Class to create.
        Returns:
        Returns the created value.
        Throws:
        NodeDeserializationException - on error.
        See Also:
        deserializeCollection(Node, Class, Class), deserializeMap(Node, Class, Class)

      • deserializeInto

        public <T> T deserializeInto​(Node value,
                             T objectToMutate)
        Invokes setters on the given objectToMutate from the provided Node.
        Type Parameters:
        T - The value to mutate using Bean style setters.
        Parameters:
        value - Value to deserialize.
        objectToMutate - Object to mutate and populate from the node.
        Returns:
        Returns the passed in value.
        Throws:
        NodeDeserializationException - on error.

      • deserializeCollection

        public <T extends java.util.Collection<?>,​U,​V extends java.util.Collection<? extends U>> V deserializeCollection​(Node value,
                                                                                                                             java.lang.Class<T> into,
                                                                                                                             java.lang.Class<U> members)
        Deserialize a Node value into a Collection T of U members.

        This method is necessary because of Java's runtime type erasure.

        Type Parameters:
        T - Type of collection value to create.
        U - Type contained within the collection.
        V - Returned collection type.
        Parameters:
        value - Value to deserialize.
        into - Collection class to create.
        members - The collection's parametric type.
        Returns:
        Returns the created collection.
        Throws:
        NodeDeserializationException - on error.
        See Also:
        deserialize(Node, Class)

      • deserializeMap

        public <T extends java.util.Map<?,​?>,​U,​V extends java.util.Map<java.lang.String,​? extends U>> V deserializeMap​(Node value,
                                                                                                                                       java.lang.Class<T> into,
                                                                                                                                       java.lang.Class<U> members)
        Deserialize a Node value into a Map T with String keys and U values.

        This method is necessary because of Java's runtime type erasure.

        Type Parameters:
        T - Type of map value to create.
        U - Type contained within the map values.
        V - Returned map type.
        Parameters:
        value - Value to deserialize.
        into - Map class to create.
        members - The maps's parametric type.
        Returns:
        Returns the created map.
        Throws:
        NodeDeserializationException - on error.
        See Also:
        deserialize(Node, Class)