# Spring Usage

In this guide we will see how we can use ShapeShift's Spring Boot starter to seamlessly add transformers and decorators within Spring projects. 

The Spring Boot starter automatically registers mapping transformer beans and decorator beans, as well as a customizer for cases where further customization of the ShapeShift instance is required.

## Installation

Install the spring library via `Maven` or `Gradle`:

### Maven

```xml
<dependency>
  <groupId>dev.krud</groupId>
  <artifactId>spring-boot-starter-shapeshift</artifactId>
  <version>0.8.0</version>
</dependency>
```

### Gradle

#### Groovy DSL

```groovy
implementation 'dev.krud:spring-boot-starter-shapeshift:0.8.0'
```

#### Kotlin DSL

```kotlin
implementation("dev.krud:spring-boot-starter-shapeshift:0.8.0")
```

## Registering Transformers

In order to register a new transformer, simply create the class and register it as a Spring Bean via your method of choice. (JavaConfig, XML)

### Annotation Example

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

```kotlin
@Component
class BeanTransformer : MappingTransformer<String, String> {
    override fun transform(context: MappingTransformerContext<out String>): String? {
        return context.originalValue?.uppercase()
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
@Component
public class BeanTransformer implements MappingTransformer<String, String> {
    @Nullable
    @Override
    public String transform(@NonNull MappingTransformerContext<? extends String> context) {
        return context.getOriginalValue() != null ? context.getOriginalValue().toUpperCase() : null;
    }
}
```

{% endtab %}
{% endtabs %}

### JavaConfig Example

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

```kotlin
@Configuration
class MyConfiguration {
    @Bean
    fun beanTransformer(): BeanTransformer {
        return BeanTransformer()
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
@Configuration
public class MyConfiguration {
    @Bean
    public BeanTransformer beanTransformer() {
        return new BeanTransformer();
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Default transformers cannot be registered in this way, see [Using Customizers](#using-customizers) below on how to achieve this
{% endhint %}

## Registering Decorators

You can register decorators  in the same way that you register transformers, simply create the class and register it as a Spring Bean via your method of choice. (JavaConfig, XML)

### Annotation Example

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

```kotlin
@Component
class BeanDecorator: MappingDecorator<MyPojo, MyPojoDisplay> {
    override fun decorate(context: MappingDecoratorContext<MyPojo, MyPojoDisplay>) {
        // decorate
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
@Component
public class BeanDecorator implements MappingDecorator<MyPojo, MyPojoDisplay> {
    @Override
    public void decorate(@NonNull MappingDecoratorContext<MyPojo, MyPojoDisplay> context) {
        // decorate
    }
}
```

{% endtab %}
{% endtabs %}

### JavaConfig Example

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

```kotlin
@Configuration
class MyConfiguration {
    @Bean
    fun beanDecorator(): BeanDecorator {
        return BeanDecorator()
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
@Configuration
public class MyConfiguration {
    @Bean
    public BeanDecorator beanDecorator() {
        return new BeanDecorator();
    }
}
```

{% endtab %}
{% endtabs %}

## Using Customizers

If you need to be able to affect the ShapeShift instance in ways that are not mentioned above, you can implement a `ShapeShiftBuilderCustomizer`, customizers are configuration classes that give you access to the `ShapeShiftBuilder` for the main Spring instance of ShapeShift. To use, simply implement the interface and annotate with `@Configuration`. In `customize`, you can do anything you're normally able to do with the standard `ShapeShiftBuilder`

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

```kotlin
@Configuration
class MyCustomizer : ShapeShiftBuilderCustomizer {
    override fun customize(builder: ShapeShiftBuilder) {
        builder.withDefaultMappingStrategy(MappingStrategy.MAP_ALL)
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
@Configuration
public class MyCustomizer implements ShapeShiftBuilderCustomizer {
    @Override
    public void customize(ShapeShiftBuilder builder) {
        builder.withDefaultMappingStrategy(MappingStrategy.MAP_ALL);
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shapeshift.krud.dev/guides/spring-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.