Package com.norconex.commons.lang.bean

# Class BeanMapper

java.lang.Object
com.norconex.commons.lang.bean.BeanMapper

public class BeanMapper extends Object

Simplified mapping of objects to/from XML, JSON, and Yaml.

## Polymorphism

Polymorphism is supported in a few different ways.

## Via Annotations

First, classes annotated with `JsonTypeInfo` and `JsonSubTypes` are properly handled by this mapper.

## Via registration

For cases where no annotations are used, you can register one or more classes (typically interfaces) that can have subclasses with `BeanMapper.BeanMapperBuilder.polymorphicType(Class, Predicate)`. When doing so, the classpath will be scanned for matching implementations and automatically register them as subtypes using their simple class name. To speed up the discovery process and avoid possible classloader issues, it is best that you provide a predicate (over fully qualified class names) to help quickly filter discovered subtypes. It relies on the "class" property to find the class reference and (de)serialize sub-types.

## Class mapping

When auto-registering subtypes, class short names are used (class name without package name). You can optionally provide in the source the full canonical name of a class to have that class recognized at deserialization time, regardless whether it was registered or not. This can be useful when dynamically adding classes that could not be previously registered for some reason.

While this mapper supports a wide variety of use cases, it is recommended to use a more elaborate serialization tool for more complex needs.

## Configurable objects

Objects implementing `Configurable` indicates that a separate class dedicated to configuration is used for bean-style mapping. By default, this mapper will ignore all properties of a configurable class except for its `getConfiguration()` method which will be treated as if annotated with `@valid`. That configuration class will be populated without the need for "configuration" wrapper elements (automatically adds `@JsonUnwrapped` This behavior can be turned off with `BeanMapper.BeanMapperBuilder.configurableDetectionDisabled(boolean)`

Since:
  3.0.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `BeanMapper.BeanMapperBuilder`
  `static enum`
  `BeanMapper.Format`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final BeanMapper`
  `DEFAULT`
  A build mapper initialized with default settings.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `assertWriteRead(@NonNull Object obj, BeanMapper.Format... formats)`
  Throws a `BeanException` if the given object is not equal to itself after writing it to specified formats and back.
  `static BeanMapper.BeanMapperBuilder`
  `builder()`
  `MultiValuedMap<Class<?>,Class<?>>`
  `getPolymorphicTypes()`
  `<T> T`
  `read(@NonNull Class<T> type, @NonNull Reader reader, @NonNull BeanMapper.Format format)`
  Reads an XML, JSON, or Yaml source and map it into a new object of the given type.
  `<T> T`
  `read(T object, @NonNull Reader reader, @NonNull BeanMapper.Format format)`
  Reads an XML, JSON, or Yaml source and map it into an existing object.
  `com.fasterxml.jackson.databind.ObjectMapper`
  `toObjectMapper(BeanMapper.Format format)`
  Gets a Jackson `ObjectMapper` for the given format.
  `void`
  `write(@NonNull Object object, @NonNull Writer writer, @NonNull BeanMapper.Format format)`
  Write the given object as XML, JSON, or Yaml.

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

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

- ## Field Details

  - ### DEFAULT

    public static final BeanMapper DEFAULT
    A build mapper initialized with default settings.

- ## Method Details

  - ### getPolymorphicTypes

    public MultiValuedMap<Class<?>,Class<?>> getPolymorphicTypes()

  - ### write

    public void write(@NonNull @NonNull Object object, @NonNull @NonNull Writer writer, @NonNull @NonNull BeanMapper.Format format)
    Write the given object as XML, JSON, or Yaml.
    Parameters:
      `object` - the object to write
      `writer` - the target to write to
      `format` - the target format to write
    Throws:
      `BeanException` - if writing failed

  - ### read

    public <T> T read(@NonNull T object, @NonNull @NonNull Reader reader, @NonNull @NonNull BeanMapper.Format format)
    Reads an XML, JSON, or Yaml source and map it into an existing object.
    Type Parameters:
      `T` - the type of the object to populate
    Parameters:
      `object` - the object to populate
      `reader` - the source content to read
      `format` - the source format
    Returns:
      populated object (same instance)
    Throws:
      `BeanException` - if reading failed
      `jakarta.validation.ConstraintViolationException` - on bean validation error

  - ### read

    public <T> T read(@NonNull @NonNull Class<T> type, @NonNull @NonNull Reader reader, @NonNull @NonNull BeanMapper.Format format)
    Reads an XML, JSON, or Yaml source and map it into a new object of the given type.
    Type Parameters:
      `T` - the type of the object returned
    Parameters:
      `type` - a class of the expected returned type
      `reader` - the source content to read
      `format` - the source format
    Returns:
      populated object
    Throws:
      `BeanException` - if reading failed
      `jakarta.validation.ConstraintViolationException` - on bean validation error

  - ### assertWriteRead

    public void assertWriteRead(@NonNull @NonNull Object obj, BeanMapper.Format... formats)
    Throws a `BeanException` if the given object is not equal to itself after writing it to specified formats and back. Not specifying any format is equivalent to testing them all (XML, JSON, and Yaml).
    Parameters:
      `obj` - the object
      `formats` - zero or more formats

  - ### toObjectMapper

    public com.fasterxml.jackson.databind.ObjectMapper toObjectMapper(BeanMapper.Format format)
    Gets a Jackson `ObjectMapper` for the given format.
    Parameters:
      `format` - format for which to get the mapper
    Returns:
      Jackson ObjectMapper

  - ### builder

    public static BeanMapper.BeanMapperBuilder builder()