Package software.amazon.smithy.model.node

Class NodeMapper

java.lang.Object
software.amazon.smithy.model.node.NodeMapper
public final class NodeMapper extends 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.

  • Constructor Details

    • NodeMapper

      public NodeMapper()

  • Method Details

    • 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(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(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 Set<Type> getDisableToNode()
      Gets the set of classes where toNode is disabled.
      Returns:
      Returns the disabled classes.

    • disableFromNodeForClass

      public void disableFromNodeForClass(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(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 Set<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(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, 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:

    • 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 Collection<?>, U, V extends Collection<? extends U>> V deserializeCollection(Node value, Class<T> into, 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:

    • deserializeMap

      public <T extends Map<?, ?>, U, V extends Map<String, ? extends U>> V deserializeMap(Node value, Class<T> into, 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: