ch.jalu.configme.beanmapper

Class MapperImpl

java.lang.Object

ch.jalu.configme.beanmapper.MapperImpl

All Implemented Interfaces:

Mapper

Direct Known Subclasses:

DefaultMapper

public class MapperImpl
extends Object
implements Mapper

Implementation of Mapper.

Maps a section of a property resource to the provided JavaBean class. The mapping is based on the bean's properties, whose names must correspond with the names in the property resource. For example, if a JavaBean class has a property length and should be mapped from the property resource's value at path definition, the mapper will look up definition.length to get the value of the JavaBean property.

Classes must be JavaBeans. These are simple classes with private fields, accompanied by getters and setters. The mapper only considers properties which have both a getter and a setter method. Any Java class without at least one property with both a getter and a setter is not considered as a JavaBean class. Such classes can be supported by implementing a custom LeafValueHandler that performs the conversion from the value coming from the property reader to an object of the class's type.

Recursion: the mapping of values to a JavaBean is performed recursively, i.e. a JavaBean may have other JavaBeans as fields and generic types at any arbitrary "depth".

Collections are only supported if they are explicitly typed, i.e. a field of List<String> is supported but List<?> and List<T extends Number> are not supported. Specifically, you may only declare fields of type List or Set, or a parent type (Collection or Iterable). Fields of type Map are supported also, with similar limitations. Additionally, maps may only have String as key type, but no restrictions are imposed on the value type.

JavaBeans may have optional fields. If the mapper cannot map the property resource value to the corresponding field, it only treats it as a failure if the field's value is null. If the field has a default value assigned to it on initialization, the default value remains and the mapping process continues. A JavaBean field whose value is null signifies a failure and stops the mapping process immediately.

Field Summary

Fields

Modifier and Type	Field and Description
static Object	RETURN_NULL Marker object to signal that null is meant to be used as value.

Constructor Summary

Constructors

Constructor and Description
MapperImpl()
MapperImpl(@NotNull BeanDescriptionFactory beanDescriptionFactory, @NotNull LeafValueHandler leafValueHandler)

Method Summary

Modifier and Type	Method and Description
@Nullable Object	convertToBean(@Nullable Object value, @NotNull TypeInformation beanType, @NotNull ConvertErrorRecorder errorRecorder) Creates an object of the given type from the given value.
protected @Nullable Object	convertValueForType(@NotNull MappingContext context, @Nullable Object value) Main method for converting a value to another type.
protected @Nullable Object	createBean(@NotNull MappingContext context, @Nullable Object value) Converts the provided value to the requested JavaBeans class if possible.
protected @NotNull Object	createBeanMatchingType(@NotNull MappingContext mappingContext) Creates an object matching the given type information.
protected @Nullable Collection	createCollection(@NotNull MappingContext context, @Nullable Object value) Handles the creation of Collection properties.
protected @NotNull Collection	createCollectionMatchingType(@NotNull MappingContext mappingContext) Creates a Collection of a type which can be assigned to the provided type.
protected @Nullable Object	createExportValueForSpecialTypes(@Nullable Object value, @NotNull Set<UUID> knownUniqueComments) Handles values of types which need special handling (such as Optional).
protected @Nullable Map	createMap(@NotNull MappingContext context, @Nullable Object value) Handles the creation of a Map property.
protected @NotNull Map	createMapMatchingType(@NotNull MappingContext mappingContext) Creates a Map of a type which can be assigned to the provided type.
protected @NotNull Object	createOptional(@NotNull MappingContext context, @Nullable Object value)
protected @NotNull MappingContext	createRootMappingContext(@NotNull TypeInformation beanType, @NotNull ConvertErrorRecorder errorRecorder)
protected @NotNull BeanDescriptionFactory	getBeanDescriptionFactory()
protected @NotNull LeafValueHandler	getLeafValueHandler()
protected @Nullable Object	handleSpecialTypes(@NotNull MappingContext context, @Nullable Object value) Handles special types in the bean mapping process which require special handling.
@Nullable Object	toExportValue(@Nullable Object value) Converts a complex type such as a JavaBean object to simple types suitable for exporting.
protected @Nullable Object	toExportValue(@Nullable Object value, @NotNull Set<UUID> knownUniqueComments) Transforms the given value to an object suitable for the export to a configuration file.
protected static @Nullable Object	unwrapReturnNull(@Nullable Object o)

Methods inherited from class java.lang.Object

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

Methods inherited from interface ch.jalu.configme.beanmapper.Mapper

convertToBean

Field Detail

RETURN_NULL

public static final Object RETURN_NULL

Marker object to signal that null is meant to be used as value.

Constructor Detail

MapperImpl

public MapperImpl()

MapperImpl

public MapperImpl(@NotNull
                  @NotNull BeanDescriptionFactory beanDescriptionFactory,
                  @NotNull
                  @NotNull LeafValueHandler leafValueHandler)

Method Detail

getBeanDescriptionFactory

@NotNull
protected final @NotNull BeanDescriptionFactory getBeanDescriptionFactory()

getLeafValueHandler

@NotNull
protected final @NotNull LeafValueHandler getLeafValueHandler()

createRootMappingContext

@NotNull
protected @NotNull MappingContext createRootMappingContext(@NotNull
                                                                    @NotNull TypeInformation beanType,
                                                                    @NotNull
                                                                    @NotNull ConvertErrorRecorder errorRecorder)

toExportValue

@Nullable
public @Nullable Object toExportValue(@Nullable
                                                @Nullable Object value)

Description copied from interface: Mapper

Converts a complex type such as a JavaBean object to simple types suitable for exporting. This method typically returns a Map of values, or simple types like String / Number for scalar values. Used in the TypeBasedProperty.toExportValue(T) method.

Specified by:

toExportValue in interface Mapper

Parameters:

value - the object to convert to its export value

Returns:

export value to use

toExportValue

@Nullable
protected @Nullable Object toExportValue(@Nullable
                                                   @Nullable Object value,
                                                   @NotNull
                                                   @NotNull Set<UUID> knownUniqueComments)

Transforms the given value to an object suitable for the export to a configuration file.

Parameters:

value - the value to transform

knownUniqueComments - UUIDs of comments which should not be repeated that have already been included

Returns:

export value to use

createExportValueForSpecialTypes

@Nullable
protected @Nullable Object createExportValueForSpecialTypes(@Nullable
                                                                      @Nullable Object value,
                                                                      @NotNull
                                                                      @NotNull Set<UUID> knownUniqueComments)

Handles values of types which need special handling (such as Optional). Null means the value is not a special type and that the export value should be built differently. Use RETURN_NULL to signal that null should be used as the export value of the provided value.

Parameters:

value - the value to convert

knownUniqueComments - UUIDs of comments which should not be repeated that have already been included

Returns:

the export value to use or RETURN_NULL, or null if not applicable

unwrapReturnNull

@Nullable
protected static @Nullable Object unwrapReturnNull(@Nullable
                                                             @Nullable Object o)

convertToBean

@Nullable
public @Nullable Object convertToBean(@Nullable
                                                @Nullable Object value,
                                                @NotNull
                                                @NotNull TypeInformation beanType,
                                                @NotNull
                                                @NotNull ConvertErrorRecorder errorRecorder)

Description copied from interface: Mapper

Creates an object of the given type from the given value. Returns null if the conversion is not possible. The value usually stems from a property resource and is a Map of values.

Specified by:

convertToBean in interface Mapper

Parameters:

value - the value to convert (typically a Map)

beanType - the required type

errorRecorder - error recorder to register errors even if a valid value is returned

Returns:

object of the given type, or null if not possible

convertValueForType

@Nullable
protected @Nullable Object convertValueForType(@NotNull
                                                         @NotNull MappingContext context,
                                                         @Nullable
                                                         @Nullable Object value)

Main method for converting a value to another type.

Parameters:

context - the mapping context

value - the value to convert from

Returns:

object whose type matches the one in the mapping context, or null if not applicable

handleSpecialTypes

@Nullable
protected @Nullable Object handleSpecialTypes(@NotNull
                                                        @NotNull MappingContext context,
                                                        @Nullable
                                                        @Nullable Object value)

Handles special types in the bean mapping process which require special handling.

Parameters:

context - the mapping context

value - the value to convert from

Returns:

object whose type matches the one in the mapping context, or null if not applicable

createCollection

@Nullable
protected @Nullable Collection createCollection(@NotNull
                                                          @NotNull MappingContext context,
                                                          @Nullable
                                                          @Nullable Object value)

Handles the creation of Collection properties.

Parameters:

context - the mapping context

value - the value to map from

Returns:

Collection property from the value, or null if not applicable

createCollectionMatchingType

@NotNull
protected @NotNull Collection createCollectionMatchingType(@NotNull
                                                                    @NotNull MappingContext mappingContext)

Creates a Collection of a type which can be assigned to the provided type.

Parameters:

mappingContext - the current mapping context with a collection type

Returns:

Collection of matching type

createMap

@Nullable
protected @Nullable Map createMap(@NotNull
                                            @NotNull MappingContext context,
                                            @Nullable
                                            @Nullable Object value)

Handles the creation of a Map property.

Parameters:

context - mapping context

value - value to map from

Returns:

Map property, or null if not applicable

createMapMatchingType

@NotNull
protected @NotNull Map createMapMatchingType(@NotNull
                                                      @NotNull MappingContext mappingContext)

Creates a Map of a type which can be assigned to the provided type.

Parameters:

mappingContext - the current mapping context with a map type

Returns:

Map of matching type

createOptional

@NotNull
protected @NotNull Object createOptional(@NotNull
                                                  @NotNull MappingContext context,
                                                  @Nullable
                                                  @Nullable Object value)

createBean

@Nullable
protected @Nullable Object createBean(@NotNull
                                                @NotNull MappingContext context,
                                                @Nullable
                                                @Nullable Object value)

Converts the provided value to the requested JavaBeans class if possible.

Parameters:

context - mapping context (incl. desired type)

value - the value from the property resource

Returns:

the converted value, or null if not possible

createBeanMatchingType

@NotNull
protected @NotNull Object createBeanMatchingType(@NotNull
                                                          @NotNull MappingContext mappingContext)

Creates an object matching the given type information.

Parameters:

mappingContext - current mapping context

Returns:

new instance of the given type