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

  • 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()