Quick Start
In this quick start guide, we'll review the simplest use-case for ShapeShift, a simple mapping between two classes.
Classes
We start by defining two classes, our source class SimpleEntity
and our destination class SimpleEntityDisplay
.
data class SimpleEntity(
val name: String,
val description: String,
val privateData: String
)
data class SimpleEntityDisplay(
val name: String = "",
val description: String = ""
)
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
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.
@DefaultMappingTarget(SimpleEntityDisplay::class)
data class SimpleEntity(
@MappedField
val name: String,
@MappedField
val description: String,
val privateData: String
)
Convert
To instantiate ShapeShift
we use the ShapeShiftBuilder
.
val shapeShift = ShapeShiftBuilder().build()
All that's left is to map the SimpleEntity
instance to the SimpleEntityDisplay
class.
val shapeShift = ShapeShiftBuilder().build()
val simpleEntity = SimpleEntity("test", "test description", "private data")
val simpleEntityDisplay = shapeShift.map<SimpleEntityDisplay>(simpleEntity)
Test
Now let's write a simple test to check this scenario.
@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")
}
Additionally, we can also pass a destination instance to the map
method, let's write a test to check this scenario as well.
@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")
}
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.
Last updated
Was this helpful?