1. Introduction

EZMorph is simple java library for transforming an Object to another Object.

EZMorph’s key strenghts are:

  • Supports transformations for primitives and Objects

  • Supports transformations for multidimensional arrays

  • Supports transformations with DynaBeans

  • Small memory footprint (~80K)

EZMorph comes with another feature: ArrayAssertions. JUnit 3.x does not have an assertEquals() method for asserting array equality, and JUnit 4.x has a limited one (it only supports Object[] not primitive arrays). With ArrayAssertions is possible to compare a boolean[] with a boolean[] or even a Boolean[], an those arrays can be multidimensional too.

EZMorph began life as the converter package on Json-lib but seeing that the features provided were more generic than JSON parsing, it became a project on its own.

1.1. Related projects

There are other projects that perform Objetc to Object conversion:

Project Name Description

Commons Beanutils

ConvertUtils: Utility methods for converting scalar String values to objects of the specified Class, String arrays to arrays of the specified Class.

Commons Lang

ArrayUtils: Operations on arrays, primitive arrays (like int[]) and primitive wrapper arrays (like Integer[]).

Commons Convert

 Commons-Convert aims to provide a single library dedicated to the task of converting an object of one type to another. The first stage will focus on Object to String and String to Object conversions.

Morph

Morph is a Java framework that eases the internal interoperability of an application. As information flows through an application, it undergoes multiple transformations. Morph provides a standard way to implement these transformations.

Lorentz

Lorentz is a generic object-to-object conversion framework. It provides a simple API to convert a Java objects of one type into an object of another type.

Spring Framework

Spring has an excellent support for PropertyEditors, that can also be used to transform Objects to/from Strings.

Dozer

Dozer is a powerful, yet simple Java Bean to Java Bean mapper that recursively copies data from one object to another. Typically, these Java Beans will be of different complex types.

2. Usage

Morphing Objects is as easy as calling morph() on a Morpher or ObjectMorpher instance. You may have noticed that Morpher does not have a morph() method but ObjectMorpher does, that is because Morpher is used on primitive Morphers and we want to avoid the prize of auto-boxing.

Using EZMorph is as straight forward as shown in the next example

int i = new IntMorpher().morph("123");
assertEquals(123, i); // true!

String str = new StringMorpher().morph(Integer.valueOf(123));
assertEquals("123", str); // true!

You can morph arrays too. It doesn’t matter how many dimensions the arrays may have, EZMorph will take care of the rest.

Boolean[] bools = new ObjectArrayMorpher(
                        new BooleanObjectMorpher()).morph(
                             new String[]{"true", "false"});
assertEquals(Boolean.TRUE, bools[0]);  // true!
assertEquals(Boolean.FALSE, bools[1]); // true!

EZMorph can also transform beans of different types, even DynaBeans from apache commons-beanutils

// will morph a BeanA into a BeanB, where a property of BeanB is also a property of BeanA
BeanA beanA = ... // initialized elsewhere
morpherRegistry.registerMorpher(new BeanMorpher(BeanB.class, morpherRegistry));
BeanB beanB = (BeanB) morpherRegistry.morph(BeanB.class, beanA);

// will morph a DynaBean into a MyBean instance
DynaBean dynaBean = ... // initialized elsewhere
morpherRegistry.registerMorpher( new BeanMorpher(MyBean.class, morpherRegistry));
MyBean myBean = (MyBean) morpherRegistry.moprh(MyBean.class, dynaBean);

EZMorph comes with a handy class for working with Morphers named MorpherRegistry. It works much like ConvertUtils on commons-beanutils. This class is not a singleton like ConvertUtils, so it is possible to have multiple registries with different Morphers that support the same target class, but take different default values or support different source classes. Another convenient class is MorphUtils, you can register standard Morphers to any MorpherRegistry with it.

MorpherRegistry morperRegistry = new MorpherRegistry();
MorphUtils.registerStandardMorphers(morpherRegistry);
Integer i = (Integer) morpherRegistry.morph(Integer.class, "A");
// "A" is not a number, so morph() returns Integer(0)
assertEquals(Integer.valueOf(0), i);

3. Build Configuration

3.1. Gradle

dependencies {
    compile 'org.kordamp.ezmorph:ezmorph:3.0.0'
}

3.2. Maven

<dependency>
    <groupId>org.kordamp.ezmorph</groupId>
    <artifactId>ezmorph</artifactId>
    <version>3.0.0</version>
</dependency>

4. Compatibility

The following lists summarizes the differences between EZMorph 2.x and 1.x

  • All classes have moved from package net.sf.ezmorph to org.kordamp.ezmorph.

  • JDK5 is the new binary base line.

  • Java Generics have been added to method signatures.

5. Links

Javadoc