# Quick Start

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

{% hint style="info" %}
Before getting started, make sure you have followed the installation steps outlined in the [Installation guide](https://shapeshift.krud.dev/introduction/installation).
{% endhint %}

## Classes

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

{% tabs %}
{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="Java" %}

```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;
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="Java" %}

```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;
    }
}
```

{% endtab %}
{% endtabs %}

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

{% hint style="info" %}
If you don't want to add annotations to your classes go to the [Kotlin DSL](https://shapeshift.krud.dev/api-documentation/dsl) or [Java Builder](https://shapeshift.krud.dev/api-documentation/java-builder) documentation to learn how to use external mapping.
{% endhint %}

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.

{% tabs %}
{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="Java" %}

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

{% endtab %}
{% endtabs %}

## Convert

To instantiate `ShapeShift` we use the `ShapeShiftBuilder`.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val shapeShift = ShapeShiftBuilder().build()
```

{% endtab %}

{% tab title="Java" %}

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

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="Java" %}

```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);
```

{% endtab %}
{% endtabs %}

## Test

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

{% tabs %}
{% tab title="Kotlin" %}

```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")
}
```

{% endtab %}

{% tab title="Java" %}

```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");
}
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Kotlin" %}

```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")
}
```

{% endtab %}

{% tab title="Java" %}

```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");
}
```

{% endtab %}
{% endtabs %}

## Full Example

You can check out the full example [here](https://github.com/krud-dev/shapeshift/tree/master/example/kotlin/simple-mapping).

## 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.