peteyan / orika-spring-boot-starter

Spring Boot Starter for Orika

orika-spring-boot-starter

Spring Boot Starter for Orika (Java Bean mapping framework).

Note: This page is for Spring Boot 2. If you use Spring Boot 1, please refer to v1.7.x branch.

Features

• Manages the MapperFacade (Orika's mapper interface) in the application context and makes it injectable into your code.
• Provides interface to customize the MapperFactory.
• Provides interface to customize the MapperFactoryBuilder.

Supported versions

"orika-spring-boot-starter" supports the following versions.
Other versions might also work, but we have not tested it.

• Java 8, 9, 10, 11
• Spring Boot 2.1.3
• Orika 1.5.4

Usage

Adding the dependency

"orika-spring-boot-starter" is published on Maven Central Repository.
If you are using Maven, add the following dependency.

<dependency>
    <groupId>net.rakugakibox.spring.boot</groupId>
    <artifactId>orika-spring-boot-starter</artifactId>
    <version>1.9.0</version>
</dependency>

Injecting the MapperFacade

The MapperFacade (Orika's mapper interface) is managed by the application context.
Inject the MapperFacade into your code.

For example:

@Autowired
private MapperFacade orikaMapperFacade;

Mapping your beans

Map your beans using the MapperFacade.

For example:

PersonSource source = new PersonSource();
source.setFirstName("John");
source.setLastName("Smith");
source.setAge(23);
PersonDestination destination = orikaMapperFacade.map(source, PersonDestination.class);

Customizing

Customizing the MapperFactory

If you need to customize the MapperFactory, create an instance of OrikaMapperFactoryConfigurer within the application context.
OrikaMapperFactoryConfigurer components are auto-detected and the configure(MapperFactory) method is called.

For example:

@Component
public class PersonMapping implements OrikaMapperFactoryConfigurer {
    @Override
    public void configure(MapperFactory orikaMapperFactory) {
        orikaMapperFactory.classMap(PersonSource.class, PersonDestination.class)
                .field("firstName", "givenName")
                .field("lastName", "sirName")
                .byDefault()
                .register();
    }
}

See also the Orika official documents:

• Declarative Mapping Configuration
• Advanced Mapping Configurations

Customizing the MapperFactoryBuilder

If you need to customize the MapperFactoryBuilder, create an instance of OrikaMapperFactoryBuilderConfigurer within the application context.
OrikaMapperFactoryBuilderConfigurer components are auto-detected and the configure(MapperFactoryBuilder) method is called.

For example:

@Component
public class CustomOrikaMapperFactoryBuilderConfigurer implements OrikaMapperFactoryBuilderConfigurer {
    @Override
    public void configure(MapperFactoryBuilder<?, ?> orikaMapperFactoryBuilder) {
        // Your customization code.
    }
}

See also the Orika official documents:

• MapperFactory Configuration

Configuration properties

"orika-spring-boot-starter" provides the following configuration properties.
These can be configure by your "application.yml" / "application.properties".

orika:
  # Whether to enable auto-configuration.
  # Defaults to true.
  enabled: true
  # Whether to use built-in converters (MapperFactoryBuilder#useBuiltinConverters(boolean)).
  # Follows Orika's behavior by default.
  useBuiltinConverters: true
  # Whether to use auto-mapping (MapperFactoryBuilder#useAutoMapping(boolean)).
  # Follows Orika's behavior by default.
  useAutoMapping: true
  # Whether to map null values (MapperFactoryBuilder#mapNulls(boolean)).
  # Follows Orika's behavior by default.
  mapNulls: true
  # Whether to dump the current state of the mapping infrastructure objects
  # upon occurrence of an exception while mapping (MapperFactoryBuilder#dumpStateOnException(boolean)).
  # Follows Orika's behavior by default.
  dumpStateOnException: false
  # Whether the class-map should be considered 'abstract' (MapperFactoryBuilder#favorExtension(boolean)).
  # Follows Orika's behavior by default.
  favorExtension: false
  # Whether full field context should be captured (MapperFactoryBuilder#captureFieldContext(boolean)).
  # Follows Orika's behavior by default.
  captureFieldContext: false

Release notes

Please refer to the "Releases" page.

Contributing

Bug reports and pull requests are welcome :)

Building and testing

To build and test, you can run:

$ cd orika-spring-boot-starter
$ ./mvnw clean install

License

Licensed under the Apache License, Version 2.0.