Test

Beanmapper

Beanmapper is a Java library for mapping dissimilar Java classes with similar names. The use cases for Beanmapper are the following:

• mapping from forms to entities, because:
  • for security reasons you want to accept only a limited number of fields as input
  • the form fields are simplified to support frontend processing
• mapping from entities to results, because:
  • you want to simplify the result for frontend processing
  • you want to expose a limited number of fields for security reasons

Maven dependency

In order to use Beanmapper in your project, simply add the following Maven dependency:

<dependency>
    <groupId>io.beanmapper</groupId>
    <artifactId>beanmapper</artifactId>
    <version>0.1.0</version>
</dependency>

Getting started

You want to map two dissimilar classes with no hierarchical relation (save java.lang.Object), but with a fairly similar naming schema for the fields.

public class SourceClass {
   public Long id;
   public String name;
   public LocalDate date;
}

public class TargetClass {
   public String name;
   public LocalDate date;
}

BeanMapper beanMapper = new BeanMapper();
SourceClass source = new SourceClass();
source.id = 42L;
source.name = "Henk";
source.date = LocalDate.of(2015, 4, 1));
TargetClass target = beanMapper.map(source, TargetClass.class);

• @BeanProperty | Referencing properties
• @BeanIgnore | Explicitly not mapping fields
• @BeanDefault | Default values when the source value is null

@BeanProperty

Beanmapper can be instructed to look for properties with different names. Either property can be annotated with the @BeanProperty annotation. Within the annotation the name value references the other property.

public class SourceClass {
   public String name;
}

public class TargetClass {
   @BeanProperty(name="name")
   public String otherName;
}

@BeanIgnore

Sometimes it is useful not to map a field, for example when you wish to perform your own operations on it instead of relying on the Beanmapper. In this case a field on either side could be annotated with the @BeanIgnore property to instruct the Beanmapper to skip the field.

public class SourceClass {
   public String name;
   public String surname;
}

public class TargetClass {
   @BeanIgnore
   public String name;
}

@BeanDefault

It is possible to control the value of the target field when the source field is null. In this case you declare a @BeanDefault annotation on either source or target side.

public class SourceClass {
   public String name;
}

public class TargetClass {
   @BeanIgnore
   public String name;
}

@BeanUnwrap

During the process of mapping it may be desirable to flatten structures. In this case, a field can be annotated with @BeanUnwrap. When the Beanmapper encounters this annotation, it will treat all the fields within that class as they were on the same level as the class they are in now. @BeanUnwrap effectively flattens layers this way.

public class SourceParent {
   public String parentName;
   @BeanUnwrap
   public SourceChild child;
}

public class SourceChild {
   public String childName;
}

public class TargetParent {
   public String parentName;
   public String childName;
}

What's more?

The library can help you with the following situations:

• nested dissimilar classes
• ignoring parts
• mapping to fields with other names, even if nested
• settings defaults if no value is found
• unwrapping class layers in order to flatten the structure
• works directly on the bean, no getters/setters required
• supports a combination of automated and manual processing

What Beanmapper is not for

Beanmapper is not a library for deep-copying classes. Whenever Beanmapper can get away with a shallow copy, it will do so. Deep-copying is reserved for dissimilar classes.