JsonSerialization (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.util, class: JsonSerialization

Package org.apache.hadoop.util

# Class JsonSerialization<T>

java.lang.Object
org.apache.hadoop.util.JsonSerialization<T>

Type Parameters:
  `T` - Type to marshal.

@Private @Evolving public class JsonSerialization<T> extends Object
Support for marshalling objects to and from JSON. It constructs an object mapper as an instance field. and synchronizes access to those methods which use the mapper. This class was extracted from `org.apache.hadoop.registry.client.binding.JsonSerDeser`, which is now a subclass of this class.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JsonSerialization(Class<T> classType, boolean failOnUnknownProperties, boolean pretty)`
  Create an instance bound to a specific type.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `T`
  `fromBytes(byte[] bytes)`
  Deserialize from a byte array.
  `T`
  `fromInstance(T instance)`
  clone by converting to JSON and back again.
  `T`
  `fromJson(String json)`
  Convert from JSON.
  `T`
  `fromJsonStream(InputStream stream)`
  Read from an input stream.
  `T`
  `fromResource(String resource)`
  Convert from a JSON file.
  `com.fasterxml.jackson.databind.ObjectMapper`
  `getMapper()`
  Get the mapper of this class.
  `String`
  `getName()`
  Get the simple name of the class type to be marshalled.
  `T`
  `load(File jsonFile)`
  Load from a JSON text file.
  `T`
  `load(FileSystem fs, Path path)`
  Load from a Hadoop filesystem.
  `T`
  `load(FileSystem fs, Path path, FileStatus status)`
  Load from a Hadoop filesystem.
  `static com.fasterxml.jackson.databind.ObjectReader`
  `mapReader()`
  `void`
  `save(File file, T instance)`
  Save to a local file.
  `void`
  `save(FileSystem fs, Path path, T instance, boolean overwrite)`
  Save to a Hadoop filesystem.
  `byte[]`
  `toBytes(T instance)`
  Convert JSON to bytes.
  `String`
  `toJson(T instance)`
  Convert an instance to a JSON string.
  `String`
  `toString(T instance)`
  Convert an instance to a string form for output.
  `void`
  `writeJsonAsBytes(T instance, OutputStream dataOutputStream)`
  Write the JSON as bytes, then close the stream.
  `static com.fasterxml.jackson.databind.ObjectWriter`
  `writer()`

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

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

- ## Constructor Details

  - ### JsonSerialization

    public JsonSerialization(Class<T> classType, boolean failOnUnknownProperties, boolean pretty)
    Create an instance bound to a specific type.
    Parameters:
      `classType` - class to marshall
      `failOnUnknownProperties` - fail if an unknown property is encountered.
      `pretty` - generate pretty (indented) output?

- ## Method Details

  - ### writer

    public static com.fasterxml.jackson.databind.ObjectWriter writer()
    Returns:
      an ObjectWriter which pretty-prints its output

  - ### mapReader

    public static com.fasterxml.jackson.databind.ObjectReader mapReader()
    Returns:
      an ObjectReader which returns simple Maps.

  - ### getName

    public String getName()
    Get the simple name of the class type to be marshalled.
    Returns:
      the name of the class being marshalled

  - ### getMapper

    public com.fasterxml.jackson.databind.ObjectMapper getMapper()
    Get the mapper of this class.
    Returns:
      the mapper

  - ### fromJson

    public T fromJson(String json) throws IOException, com.fasterxml.jackson.core.JsonParseException, com.fasterxml.jackson.databind.JsonMappingException
    Convert from JSON.
    Parameters:
      `json` - input
    Returns:
      the parsed JSON
    Throws:
      `IOException` - IO problems
      `com.fasterxml.jackson.core.JsonParseException` - If the input is not well-formatted
      `com.fasterxml.jackson.databind.JsonMappingException` - failure to map from the JSON to this class

  - ### fromJsonStream

    public T fromJsonStream(InputStream stream) throws IOException
    Read from an input stream.
    Parameters:
      `stream` - stream to read from
    Returns:
      the parsed entity
    Throws:
      `IOException` - IO problems
      `com.fasterxml.jackson.core.JsonParseException` - If the input is not well-formatted
      `com.fasterxml.jackson.databind.JsonMappingException` - failure to map from the JSON to this class

  - ### load

    public T load(File jsonFile) throws IOException, com.fasterxml.jackson.core.JsonParseException, com.fasterxml.jackson.databind.JsonMappingException
    Load from a JSON text file.
    Parameters:
      `jsonFile` - input file
    Returns:
      the parsed JSON
    Throws:
      `IOException` - IO problems
      `com.fasterxml.jackson.core.JsonParseException` - If the input is not well-formatted
      `com.fasterxml.jackson.databind.JsonMappingException` - failure to map from the JSON to this class

  - ### save

    public void save(File file, T instance) throws IOException
    Save to a local file. Any existing file is overwritten unless the OS blocks that.
    Parameters:
      `file` - file
      `instance` - instance
    Throws:
      `IOException` - IO exception

  - ### fromResource

    public T fromResource(String resource) throws IOException, com.fasterxml.jackson.core.JsonParseException, com.fasterxml.jackson.databind.JsonMappingException
    Convert from a JSON file.
    Parameters:
      `resource` - input file
    Returns:
      the parsed JSON
    Throws:
      `IOException` - IO problems
      `com.fasterxml.jackson.core.JsonParseException` - If the input is not well-formatted
      `com.fasterxml.jackson.databind.JsonMappingException` - failure to map from the JSON to this class

  - ### fromInstance

    public T fromInstance(T instance) throws IOException
    clone by converting to JSON and back again. This is much less efficient than any Java clone process.
    Parameters:
      `instance` - instance to duplicate
    Returns:
      a new instance
    Throws:
      `IOException` - IO problems.

  - ### load

    public T load(FileSystem fs, Path path) throws IOException
    Load from a Hadoop filesystem.
    Parameters:
      `fs` - filesystem
      `path` - path
    Returns:
      a loaded object
    Throws:
      `PathIOException` - JSON parse problem
      `IOException` - IO problems

  - ### load

    public T load(FileSystem fs, Path path, @Nullable FileStatus status) throws IOException
    Load from a Hadoop filesystem. If a file status is supplied, it's passed in to the openFile() call so that FS implementations can optimize their opening.
    Parameters:
      `fs` - filesystem
      `path` - path
      `status` - status of the file to open.
    Returns:
      a loaded object
    Throws:
      `PathIOException` - JSON parse problem
      `EOFException` - file status references an empty file
      `IOException` - IO problems

  - ### save

    public void save(FileSystem fs, Path path, T instance, boolean overwrite) throws IOException
    Save to a Hadoop filesystem.
    Parameters:
      `fs` - filesystem
      `path` - path
      `overwrite` - should any existing file be overwritten
      `instance` - instance
    Throws:
      `IOException` - IO exception.

  - ### writeJsonAsBytes

    public void writeJsonAsBytes(T instance, OutputStream dataOutputStream) throws IOException
    Write the JSON as bytes, then close the stream.
    Parameters:
      `instance` - instance to write
      `dataOutputStream` - an output stream that will always be closed
    Throws:
      `IOException` - on any failure

  - ### toBytes

    public byte[] toBytes(T instance) throws IOException
    Convert JSON to bytes.
    Parameters:
      `instance` - instance to convert
    Returns:
      a byte array
    Throws:
      `IOException` - IO problems

  - ### fromBytes

    public T fromBytes(byte[] bytes) throws IOException
    Deserialize from a byte array.
    Parameters:
      `bytes` - byte array
    Returns:
      byte array.
    Throws:
      `IOException` - IO problems
      `EOFException` - not enough data

  - ### toJson

    public String toJson(T instance) throws com.fasterxml.jackson.core.JsonProcessingException
    Convert an instance to a JSON string.
    Parameters:
      `instance` - instance to convert
    Returns:
      a JSON string description
    Throws:
      `com.fasterxml.jackson.core.JsonProcessingException` - Json generation problems

  - ### toString

    public String toString(T instance)
    Convert an instance to a string form for output. This is a robust operation which will convert any JSON-generating exceptions into error text.
    Parameters:
      `instance` - non-null instance
    Returns:
      a JSON string