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.
data class SimpleEntity(
val name: String,
val description: String,
val privateData: String
)
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;
}
}
data class SimpleEntityDisplay(
val name: String = "",
val description: String = ""
)
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.
@DefaultMappingTarget(SimpleEntityDisplay::class)
data class SimpleEntity(
@MappedField
val name: String,
@MappedField
val description: String,
val privateData: String
)
@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.
val shapeShift = ShapeShiftBuilder().build()
ShapeShift shapeShift = new 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)
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.
@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")
}
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.
