Quick Start

In this quick start guide, we'll review the simplest use-case for ShapeShift, a simple mapping between two classes.

Before getting started, make sure you have followed the installation steps outlined in the Installation guide.

Classes

We start by defining two classes, our source class SimpleEntity and our destination class SimpleEntityDisplay.

Kotlin

data class SimpleEntity(
    val name: String,
    val description: String,
    val privateData: String
)

Java

public class SimpleEntity {
    private String name;
    private String description;
    private String privateData;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getPrivateData() {
        return privateData;
    }

    public void setPrivateData(String privateData) {
        this.privateData = privateData;
    }
}

Kotlin

data class SimpleEntityDisplay(
    val name: String = "",
    val description: String = ""
)

Java

public class SimpleEntityDisplay {
    private String name = "";
    private String description = "";

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }
}

Due to the fact that ShapeShift uses reflection behind the scenes, destination classes should have a no arg constructor. Alternatively, you can also pass already-instantiated destination objects to the map method.

Annotations

If you don't want to add annotations to your classes go to the Kotlin DSL or Java Builder documentation to learn how to use external mapping.

We can now start adding our annotations to the SimpleEntity class. In this example, we want to map the name and description fields to the name and description fields of the SimpleEntityDisplay class, but not the privateData field.

To achieve this, we will use the @MappedField annotation on both of these fields. Additionally, we will define @DefaultMappingTarget on the SimpleEntity class, which will indicate that all fields annotated with @MappedField that do not specify a target should be mapped to the SimpleEntityDisplay class.

Kotlin

@DefaultMappingTarget(SimpleEntityDisplay::class)
data class SimpleEntity(
    @MappedField
    val name: String,
    @MappedField
    val description: String,
    val privateData: String
)

Java

@DefaultMappingTarget(SimpleEntityDisplay.class)
public class SimpleEntity {
    @MappedField
    private String name;
    @MappedField
    private String description;
    private String privateData;
    // Getters and Setters...
}

Convert

To instantiate ShapeShift we use the ShapeShiftBuilder.

Kotlin

val shapeShift = ShapeShiftBuilder().build()

Java

ShapeShift shapeShift = new ShapeShiftBuilder().build();

All that's left is to map the SimpleEntity instance to the SimpleEntityDisplay class.

Kotlin

val shapeShift = ShapeShiftBuilder().build()
val simpleEntity = SimpleEntity("test", "test description", "private data")
val simpleEntityDisplay = shapeShift.map<SimpleEntityDisplay>(simpleEntity)

Java

ShapeShift shapeShift = new ShapeShiftBuilder().build();
SimpleEntity simpleEntity = new SimpleEntity();
simpleEntity.setName("test");
simpleEntity.setDescription("test description");
simpleEntity.setPrivateData("private data");
SimpleEntityDisplay simpleEntityDisplay = shapeShift.map(simpleEntity, SimpleEntityDisplay.class);

Test

Now let's write a simple test to check this scenario.

Kotlin

@Test
internal fun `test simple mapping`() {
    val shapeShift = ShapeShiftBuilder().build()
    val simpleEntity = SimpleEntity("test", "test description", "private data")
    val result = shapeShift.map<SimpleEntityDisplay>(simpleEntity)
    expectThat(result.name)
        .isEqualTo("test")
    expectThat(result.description)
        .isEqualTo("test description")
}

Java

@Test
public void testSimpleMapping() {
    ShapeShift shapeShift = new ShapeShiftBuilder().build();
    SimpleEntity simpleEntity = new SimpleEntity();
    simpleEntity.setName("test");
    simpleEntity.setDescription("test description");
    simpleEntity.setPrivateData("private data");
    SimpleEntityDisplay simpleEntityDisplay = shapeShift.map(simpleEntity, SimpleEntityDisplay.class);
    assertEquals(simpleEntityDisplay.getName(), "test");
    assertEquals(simpleEntityDisplay.getDescription(), "test description");
}

Additionally, we can also pass a destination instance to the map method, let's write a test to check this scenario as well.

Kotlin

@Test
internal fun `test simple mapping with premade destination instance`() {
    val shapeShift = ShapeShiftBuilder().build()
    val simpleEntity = SimpleEntity("test", "test description", "private data")
    val result = shapeShift.map(simpleEntity, SimpleEntityDisplay())
    expectThat(result.name)
        .isEqualTo("test")
    expectThat(result.description)
        .isEqualTo("test description")
}

Java

@Test
public void testSimpleMappingWithPremadeDestinationInstance() {
    ShapeShift shapeShift = new ShapeShiftBuilder().build();
    SimpleEntity simpleEntity = new SimpleEntity();
    simpleEntity.setName("test");
    simpleEntity.setDescription("test description");
    simpleEntity.setPrivateData("private data");
    SimpleEntityDisplay simpleEntityDisplay = shapeShift.map(simpleEntity, new SimpleEntityDisplay());
    assertEquals(simpleEntityDisplay.getName(), "test");
    assertEquals(simpleEntityDisplay.getDescription(), "test description");
}

Full Example

You can check out the full example here.

Next Steps

We hope this quick start guide has given you a glimpse of the simplicity and power of ShapeShift. There's much more to learn, and we encourage you to keep reading about all of the different options available by reading their respective API documentation.