BULL - Bean Utils Light Library
BULL is a Java Bean to Java Bean transformer that recursively copies data from one object to another, it is generic, flexible, reusable, configurable, and incredibly fast.
It’s the only library able to transform Mutable, Immutable, and Mixed bean without any custom configuration.
All BULL modules are available on Maven Central:
It contains all the modules available in the project
<dependency>
<groupId>com.expediagroup.beans</groupId>
<artifactId>bull-bom</artifactId>
<version>x.y.z</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.expediagroup.beans</groupId>
<artifactId>bull-bean-transformer</artifactId>
<version>x.y.z</version>
</dependency>
Map
Transformer
<dependency>
<groupId>com.expediagroup.beans</groupId>
<artifactId>bull-map-transformer</artifactId>
<version>x.y.z</version>
</dependency>
The project provides two different builds, one compatible with jdk 8
(or above),
one with jdk 11
and on with jdk 15
or above.
In case you need to integrate it in a:
jdk 8
please refer to CHANGELOG-JDK8
jdk 11
please refer to CHANGELOG-JDK11
jdk 15
CHANGELOG
Some jdk versions remove the Java Bean constructor’s argument names from the compiled code and this may cause problems to the library.
On top of that, it’s suggested to configure the maven-compiler-plugin
, inside your project, as follow:
<build>
...
<pluginManagement>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven.compiler.plugin.version}</version>
<configuration>
<source>${maven.compiler.source}</source>
<target>${maven.compiler.target}</target>
<parameters>true</parameters>
<forceJavacCompilerUse>true</forceJavacCompilerUse>
</configuration>
</plugin>
</plugins>
</pluginManagement>
...
</build>
Full build
./mvnw clean install
or on Windows
mvnw.cmd clean install
./mvnw clean install -P relaxed
or on Windows
mvnw.cmd clean install -P relaxed
mvn versions:display-dependency-updates -P check-for-updates
or on Windows
mvnw.cmd versions:display-dependency-updates -P check-for-updates
List<BeanA> => List<BeanB>
Map<String, Map<String, String>>
String[]
=> String[]
BeanA[]
=> BeanB[]
int id => int userId
public class FromBean { public class ToBean {
private final String name; @NotNull
private final BigInteger id; public BigInteger id;
private final List<FromSubBean> subBeanList; private final String name;
private List<String> list; private final List<String> list;
private final FromSubBean subObject; private final List<ToSubBean> subBeanList;
private ImmutableToSubFoo subObject;
// all constructors // all args constructor
// getters and setters... // getters and setters...
}
And one line code as:
ToBean toBean = beanUtils.getTransformer().transform(fromBean, ToBean.class);
From class and To class with different field names:
public class FromBean { public class ToBean {
private final String name; private final String differentName;
private final int id; private final int id;
private final List<FromSubBean> subBeanList; private final List<ToSubBean> subBeanList;
private final List<String> list; private final List<String> list;
private final FromSubBean subObject; private final ToSubBean subObject;
// getters...
public ToBean(final String differentName,
final int id,
} final List<ToSubBean> subBeanList,
final List<String> list,
final ToSubBean subObject) {
this.differentName = differentName;
this.id = id;
this.subBeanList = subBeanList;
this.list = list;
this.subObject = subObject;
}
// getters...
}
And one line code as:
beanUtils.getTransformer().withFieldMapping(new FieldMapping<>("name", "differentName")).transform(fromBean, ToBean.class);
it is also possible to map a field in the source class into multiple fields in the destination object.
Given the following source class:
public class SourceClass {
private final String name;
private final int id;
}
the following destination class:
public class DestinationClass {
private final String name;
private final int id;
private final int index;
}
and the following operations:
var sourceObj = new SourceClass("foo", 123);
var multipleFieldMapping = new FieldMapping<>("id", "index", "identifier");
var destObj = new BeanUtils().getBeanTransformer()
.withFieldMapping(multipleFieldMapping)
.transform(sourceObj, DestinationClass.class);
System.out.println("name = " + destObj.getName());
System.out.println("id = " + destObj.getId());
System.out.println("index = " + destObj.getIndex());
the output will be:
name = foo
id = 123
index = 123
Assuming that the object FromSubBean
is declared as follow:
public class FromSubBean {
private String serialNumber;
private Date creationDate;
// getters and setters...
}
and our source object and destination object are described as follow:
public class FromBean { public class ToBean {
private final int id; private final int id;
private final String name; private final String name;
private final FromSubBean subObject; private final String serialNumber;
private final Date creationDate;
// all args constructor // all args constructor
// getters... // getters...
} }
the fields: serialNumber
and creationDate
needs to be retrieved from subObject
, this can be done by defining the whole path to the end property:
FieldMapping serialNumberMapping = new FieldMapping<>("subObject.serialNumber", "serialNumber");
FieldMapping creationDateMapping = new FieldMapping<>("subObject.creationDate", "creationDate");
beanUtils.getTransformer()
.withFieldMapping(serialNumberMapping, creationDateMapping)
.transform(fromBean, ToBean.class);
public class FromBean { public class ToBean {
private final String name; private final String differentName;
private final int id; private final int id;
private final List<FromSubBean> subBeanList; private final List<ToSubBean> subBeanList;
private final List<String> list; private final List<String> list;
private final FromSubBean subObject; private final ToSubBean subObject;
// all args constructor
// getters...
public ToBean(@ConstructorArg("name") final String differentName,
@ConstructorArg("id") final int id,
} @ConstructorArg("subBeanList") final List<ToSubBean> subBeanList,
@ConstructorArg(fieldName ="list") final List<String> list,
@ConstructorArg("subObject") final ToSubBean subObject) {
this.differentName = differentName;
this.id = id;
this.subBeanList = subBeanList;
this.list = list;
this.subObject = subObject;
}
// getters...
}
And one line code as:
ToBean toBean = beanUtils.getTransformer().transform(fromBean, ToBean.class);
public class FromBean { public class ToBean {
private final String name; @NotNull
private final BigInteger id; public BigInteger identifier;
private final BigInteger index; public BigInteger index;
private final List<FromSubBean> subBeanList; private final String name;
private List<String> list; private final List<String> list;
private final FromSubBean subObject; private final List<ImmutableToSubFoo> nestedObjectList;
private final String locale; private final Locale locale;
private ImmutableToSubFoo nestedObject;
// constructors... // constructors...
// getters and setters... // getters and setters...
} }
FieldTransformer<BigInteger, BigInteger> fieldTransformer = new FieldTransformer<>("identifier", BigInteger::negate);
FieldTransformer<String, Locale> localeTransformer = new FieldTransformer<>("locale", Locale::forLanguageTag);
beanUtils.getTransformer()
.withFieldMapping(new FieldMapping<>("id", "identifier"))
.withFieldTransformer(fieldTransformer).transform(fromBean, ToBean.class)
.withFieldTransformer(localeTransformer);
It’s also possible to apply the same transformation function on multiple fields. Taking as an example the above bean and
assuming that we would negate both the id and the identifier, the transformer function has to be defined as follows:
FieldTransformer<BigInteger, BigInteger> fieldTransformer = new FieldTransformer<>(List.of("identifier", "index"), BigInteger::negate);
Assign a default value in case of a missing field in the source object:
public class FromBean { public class ToBean {
private final String name; @NotNull
private final BigInteger id; public BigInteger id;
private final String name;
private String notExistingField; // this will be null and no exceptions will be raised
// constructors... // constructors...
// getters... // getters and setters...
} }
And one line code as:
ToBean toBean = beanUtils.getTransformer()
.setDefaultValueForMissingField(true).transform(fromBean, ToBean.class);
BULL by default sets the default value for all primitive types fields in case their value is in the source object.
Given the following Java Bean:
public class FromBean { public class ToBean {
private final String name; @NotNull
private final BigInteger id; public BigInteger id;
private final String name;
// constructors... // constructors...
// getters... // getters and setters...
} }
in case the field id
in the FromBean
object is null
, the value assigned the correspondent field in the ToBean
object will be 0
.
To disable this you can simply do:
ToBean toBean = beanUtils.getTransformer()
.setDefaultValueForMissingPrimitiveField(false).transform(fromBean, ToBean.class);
in this case, the field id
after the transformation will be null
Assign a default value in case of a missing field in the source object:
public class FromBean { public class ToBean {
private final String name; @NotNull
private final BigInteger id; public BigInteger id;
private final String name;
private String notExistingField; // this will have value: sampleVal
// all args constructor // constructors...
// getters... // getters and setters...
} }
And one line code as:
FieldTransformer<String, String> notExistingFieldTransformer = new FieldTransformer<>("notExistingField", () -> "sampleVal");
ToBean toBean = beanUtils.getTransformer()
.withFieldTransformer(notExistingFieldTransformer)
.transform(fromBean, ToBean.class);
This example shows how a lambda transformation function can be applied to a nested object field.
Given:
public class FromBean { public class ToBean {
private final String name; private final String name;
private final FromSubBean nestedObject; private final ToSubBean nestedObject;
// all args constructor // all args constructor
// getters... // getters...
} }
and
public class ToSubBean {
private final String name;
private final long index;
}
Assuming that the lambda transformation function should be applied only to field: name
contained into the ToSubBean
object, the transformation function has to be defined as
follow:
FieldTransformer<String, String> nameTransformer = new FieldTransformer<>("nestedObject.name", StringUtils::capitalize);
ToBean toBean = beanUtils.getTransformer()
.withFieldTransformer(nameTransformer)
.transform(fromBean, ToBean.class);
This example shows how to map a primitive field into a nested object into the destination one.
Given:
public class FromBean { public class ToBean {
private final String name; private final String name;
private final FromSubBean nestedObject; private final ToSubBean nestedObject;
private final int x;
// all args constructor // all args constructor
// getters... // getters...
} }
and
public class ToSubBean {
private final int x;
// all args constructor
} // getters...
Assuming that the value x
should be mapped into the field: x
contained into the ToSubBean
object, the field mapping has to be defined as
follow:
ToBean toBean = beanUtils.getTransformer()
.withFieldMapping(new FieldMapping<>("x", "nestedObject.x"));
This example shows how a lambda transformation function can be applied to all fields matching with the given one independently from their position.
Given:
public class FromBean { public class ToBean {
private final String name; private final String name;
private final FromSubBean nestedObject; private final ToSubBean nestedObject;
// all args constructor // all args constructor
// getters... // getters...
} }
and
public class FromSubBean { public class ToSubBean {
private final String name; private final String name;
private final long index; private final long index;
// all args constructor // all args constructor
// getters... // getters...
} }
Assuming that the lambda transformation function should be applied only to the field: name
contained in the ToSubBean
object, the transformation function has to be defined
as
follow:
FieldTransformer<String, String> nameTransformer = new FieldTransformer<>("name", StringUtils::capitalize);
ToBean toBean = beanUtils.getTransformer()
.setFlatFieldNameTransformation(true)
.withFieldTransformer(nameTransformer)
.transform(fromBean, ToBean.class);
List<FromFooSimple> fromFooSimpleList = Arrays.asList(fromFooSimple, fromFooSimple);
can be transformed as follow:
Function<FromFooSimple, ImmutableToFooSimple> transformerFunction = BeanUtils.getTransformer(ImmutableToFooSimple.class);
List<ImmutableToFooSimple> actual = fromFooSimpleList.stream()
.map(transformerFunction)
.collect(Collectors.toList());
or if you have a pre-configured transformer:
Function<FromFooSimple, ImmutableToFooSimple> transformerFunction = BeanUtils.getTransformer(<yourPreconfiguredTransformer>, ImmutableToFooSimple.class);
List<ImmutableToFooSimple> actual = fromFooSimpleList.stream()
.map(transformerFunction)
.collect(Collectors.toList());
Assuming that the field: id
in the fromBean instance is null.
public class FromBean { public class ToBean {
private final String name; @NotNull
private final BigInteger id; public BigInteger id;
private final String name;
// all args constructor // all args constructor
// getters... // getters and setters...
} }
adding the following configuration an exception will be thrown:
ToBean toBean = beanUtils.getTransformer()
.setValidationEnabled(true)
.transform(fromBean, ToBean.class);
Given:
public class FromBean { public class ToBean {
private final String name; private String name;
private final FromSubBean nestedObject; private ToSubBean nestedObject;
// all args constructor // constructor
// getters... // getters and setters...
} }
if you need to perform the copy on an already existing object, just do:
ToBean toBean = new ToBean();
beanUtils.getTransformer().transform(fromBean, toBean);
Given:
public class FromBean { public class ToBean {
private final String name; private String name;
private final FromSubBean nestedObject; private ToSubBean nestedObject;
// all args constructor // constructor
// getters... // getters and setters...
} }
public class FromBean2 {
private final int index;
private final FromSubBean nestedObject;
// all args constructor
// getters...
}
if you need to skip the transformation for a given field, just do:
ToBean toBean = new ToBean();
beanUtils.getTransformer()
.skipTransformationForField("nestedObject")
.transform(fromBean, toBean);
where nestedObject
is the name of the field in the destination object.
This feature allows us to transform an object keeping the data from different sources.
To better explain this function let’s assume that the ToBean
(defined above) should be transformed as follow:
name
field value has been taken from the FromBean
objectnestedObject
field value has been taken from the FromBean2
objectthe objective can be reached by doing:
// create the destination object
ToBean toBean = new ToBean();
// execute the first transformation skipping the copy of: 'nestedObject' field that should come from the other source object
beanUtils.getTransformer()
.skipTransformationForField("nestedObject")
.transform(fromBean, toBean);
// then execute the transformation skipping the copy of: 'name' field that should come from the other source object
beanUtils.getTransformer()
.skipTransformationForField("name")
.transform(fromBean2, toBean);
Given:
public class FromBean { public class ToBean {
private final String name; private String name;
private final DateTime dateTime; private final DateTime dateTime;
// all args constructor // constructor
// getters... // getters and setters...
} }
if you need to keep the value of a field type from the source object as it, you can add all the types you want to keep as they are
by doing:
ClassUtils.CUSTOM_SPECIAL_TYPES.add(DateTime.class);
ToBean toBean = new ToBean();
beanUtils.getTransformer()
.transform(fromBean, toBean);
In case the destination class has a field that does not exist in the source object, but it contains a getter method returning the value, the library should gets the field value from that method.
public class FromBean { public class ToBean {
private final BigInteger id;
public BigInteger getId() {
return BigInteger.TEN; // all args constructor
} // getters...
}
}
And one line code as:
ToBean toBean = beanUtils.getTransformer().transform(fromBean, ToBean.class);
Given the following Java Bean:
public class FromBean { public class ToBean {
private final String indexNumber; private final int indexNumber;
private final BigInteger id; public Long id;
// constructors... // constructors...
// getters... // getters and setters...
} }
as, by default the primitive type conversion is disabled, to get the above object converted we should have
implemented transformer functions for both field indexNumber
and id
, but this can be done automatically by enabling the
the functionality described above.
Transformer transformer = beanUtils.getTransformer()
.setPrimitiveTypeConversionEnabled(true);
ToBean toBean = transformer.transform(fromBean, ToBean.class);
IMPORTANT: The primitive type transformation (if enabled) is executed before any other FieldTransformer
function is defined on a specific field.
This means that once the FieldTransformer
function will be executed the field value has already been transformed.
The library supports the transformation of Java Bean using the following Builder patterns:
public class ItemType {
private final Class<?> objectClass;
private final Class<?> genericClass;
ItemType(final Class<?> objectClass, final Class<?> genericClass) {
this.objectClass = objectClass;
this.genericClass = genericClass;
}
public static ItemTypeBuilder builder() {
return new ItemType.ItemTypeBuilder();
}
// getter methods
public static class ItemTypeBuilder {
private Class<?> objectClass;
private Class<?> genericClass;
ItemTypeBuilder() {
}
public ItemTypeBuilder objectClass(final Class<?> objectClass) {
this.objectClass = objectClass;
return this;
}
public ItemTypeBuilder genericClass(final Class<?> genericClass) {
this.genericClass = genericClass;
return this;
}
public ItemType build() {
return new ItemType(this.objectClass, this.genericClass);
}
}
}
To enable the transformation of Java Beans using the following Builder pattern:
public class ItemType {
private final Class<?> objectClass;
private final Class<?> genericClass;
ItemType(final ItemTypeBuilder builder) {
this.objectClass = builder.objectClass;
this.genericClass = builder.genericClass;
}
public static ItemTypeBuilder builder() {
return new ItemType.ItemTypeBuilder();
}
// getter methods
public static class ItemTypeBuilder {
private Class<?> objectClass;
private Class<?> genericClass;
ItemTypeBuilder() {
}
public ItemTypeBuilder objectClass(final Class<?> objectClass) {
this.objectClass = objectClass;
return this;
}
public ItemTypeBuilder genericClass(final Class<?> genericClass) {
this.genericClass = genericClass;
return this;
}
public ItemType build() {
return new ItemType(this);
}
}
}
It’s needed to enable the custom Builder Transformation as follows:
ToBean toBean = new BeanTransformer()
.setCustomBuilderTransformationEnabled(true)
.transform(sourceObject, ToBean.class);
public record FromFooRecord(BigInteger id, String name) { public record RecordToFoo(BigInteger id, String name) {
} }
And one line code as:
var toBean = beanUtils.getTransformer().transform(fromBean, RecordToFoo.class);
More sample beans can be found in the test package: com.expediagroup.beans.sample
Following a comparison between the BULL functionalities and the following Third-Party libraries:
BULL | Apache Bean Utils | Jackson | Dozer | |
---|---|---|---|---|
Mutable bean copy | X | X | X | X+ |
Mutable bean with nested objects | X | - | X | X+ |
Mutable bean extending classes | X | - | X | X+ |
Immutable bean copy | X | - | - | X* |
Mixed bean copy | X | - | - | X+ |
Copy of beans without getter and setter methods defined | X | - | - | - |
Mutable Bean with different field’s name | X | - | - | X+ |
Mixed with different field’s type | X | - | - | X+ |
Immutable with different field’s type | X | - | - | X+ |
Mutable Bean containing collection type fields containing complex objects | X | - | X | X |
Mixed Bean containing collection type fields containing complex objects | X | - | - | X+ |
Immutable Bean containing collection type fields containing complex objects | X | - | - | X+ |
Mutable Bean containing containing Map type fields with nested Maps inside. e.g. Map<String, Map<String, Integer>> |
X | - | X | X |
Mixed Bean containing containing Map type fields with nested Maps inside. e.g. Map<String, Map<String, Integer>> |
X | - | - | X+ |
Immutable Bean containing containing Map type fields with nested Maps inside. e.g. Map<String, Map<String, Integer>> |
X | - | - | X+ |
Annotation field validation | X | - | X | - |
[*] Immutable types are not supported by Dozer. When a type doesn’t have a no-arg constructor and all fields are final, Dozer can’t perform the mapping.
A workaround is introducing the Builder Pattern. An example can be found here
[+] Requires a custom configuration
Let’s have a look at the performance library performance. The test has been executed on the following objects:
Mutable | Immutable | Mixed | |
---|---|---|---|
Simple objects (without nested objects) | ~0.011ms | ~0.018ms | NA |
Complex objects (containing several nested object and several items in Map and Array objects) | ~0.37ms | ~0.21ms | ~0.22ms |
CPU/Heap usage | ~0.2%/35 MB | ~0.2%/30 MB | ~0.2%/25 MB |
Transformation time screenshot
The Bean Utils library has been tested on a real case scenario integrating it into a real edge service (called BPE).
The purpose was to compare the latency introduced by the library plus the memory/CPU usage.
The dashboard’s screenshot shows the latency of the invoked downstream service (called BPAS) and the one where the library has been installed (BPE).
Following the obtained results:
Classic transformer | BeanUtils library | |
---|---|---|
Throughput per second | 60 | 60 |
Average CPU usage | 0.3% | 0.3% |
Min/Max Heap Memory Usage (MB) | 90/320 | 90/320 |
Average Latency than the downstream service | +2ms | +2ms |
JVM stats screenshot | screenshot | screenshot |
Dashboard screenshot | screenshot | screenshot |
Validating a java bean has never been so simple. The library offers different APIs related to this, following some examples:
Given the following bean:
public class SampleBean {
@NotNull
private BigInteger id;
private String name;
// constructor
// getters and setters...
}
an instance of the above object:
SampleBean sampleBean = new SampleBean();
And one line code as:
beanUtils.getValidator().validate(sampleBean);
this will throw an InvalidBeanException
as the id
field is null.
Given the following bean:
public class SampleBean {
@NotNull
private BigInteger id;
private String name;
// constructor
// getters and setters...
}
an instance of the above object:
SampleBean sampleBean = new SampleBean();
And one line code as:
List<String> violatedConstraints = beanUtils.getValidator().getConstraintViolationsMessages(sampleBean);
this will return a list containing a constraint validation message for the id
field as it’s null and the constraint: @NotNull
is not met.
in case it’s needed to have the ConstraintViolation
object:
Set<ConstraintViolation<Object>> violatedConstraints = beanUtils.getValidator().getConstraintViolations(sampleBean);
Converts a given primitive value into the given primitive type.
The supported types, in which an object can be converted (from/to), are:
Byte
, byte
or byte[]
Short
or short
Integer
or int
Long
or long
Float
or float
Double
or double
BigDecimal
BigInteger
Character
or char
Boolean
or boolean
String
Given the following variable:
String indexNumber = "26062019";
to convert it in an int
:
Converter converter = new BeanUtils().getPrimitiveTypeConverter();
int indexNumber = converter.convertValue(indexNumber, int.class);
It’s possible to obtain a type conversion function, reusable several times in different places.
Assuming that the required conversion is from char
to `byte
char c = '1';
the conversion function is retrieved through:
Converter converter = new BeanUtils().getPrimitiveTypeConverter();
Optional<Function<Object, Object>> conversionFunction = converter.getConversionFunction(char.class, byte.class);
byte converted = conversionFunction.map(processor -> processor.apply(c)).orElse(0);
Optional
TypeConversionException
Map
transformation samplesSamples on how to transform a Map
and all others function applicable to it can be viewed here
Detailed project documentation is available here, including some samples for testing the library inside your project.
An article that explains how it works, with suggestions and examples, is available on DZone: How to Transform Any Type of Java Bean With BULL
Created by: Fabio Borriello with the contribution of: Patrizio Munzi,
Andrea Marsiglia, Giorgio Delle Grottaglie & the Hotels.com’s Checkout team in Rome.
The application’s logo has been designed by Rob Light.
All the instructions for releasing a new version are available at RELEASES.md
Add the following snippet in your Markdown file:
[![Bull enabled](https://img.shields.io/badge/bull-enabled-red?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAA8FBMVEUAAADRKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi/RKi////+bJRrYAAAATnRSTlMAABoFB0UGATtcHQsinVIEAz3Dy6QwHmzlylsTl/uGVvXonjMm0+pLApjjNO3nv0H3/N9VTVnauEn49r391vCCcnsJCn76aa6LFxnVZrus5DL8AAAApElEQVR42k2NA7rDABAGM89mbZupbbd7/9sU8Xzc/aUYwN09igMeHp+eHR94eX17tx/w8fn1+m08gJ/fv3+XG+vh8fpE/AEPGI9gKCxXIrYlGhOJJ5KWI5UWyWRzmBP3+au/UASe0Qy/peujXKlyr9XyHJIrtbraaLa0x1tbdGKdlPbo9vqDQX84GstEu5kOZ/PFcrXOqpsf7bFN72B/mHA8LVAuoY0XA5ziPJYAAAAASUVORK5CYII=)](https://github.com/ExpediaGroup/bull)
For any question, proposal, or help, please refer to the slack channel: #bull.
This project is available under the Apache 2.0 License.
Copyright 2018-2023 Expedia Inc.