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

Kotlin

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

Java

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

Convert

To instantiate ShapeShift we use the ShapeShiftBuilder.

Kotlin

val shapeShift = ShapeShiftBuilder().build()

Java

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

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

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

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.