Skip to content

Maven Kotlinx Serialization Support

Jump to bottom
dermakov edited this page Apr 29, 2023 · 4 revisions

Kobby supports Kotlinx Serialization to provide an ability to generate Multiplatform GraphQL DSL Client since release 3.0.0.

Examples

Maven example

Requirements

  • Kobby at least version 3.0.0 is required.
  • Maven at least version 3.9.1 is required.
  • Kotlin at least version 1.8.0 is required.
  • Kotlinx Serialization at least 1.5.0 is required.
  • Ktor at least version 2.0.0 is required for default adapters.

Implicit setup

To enable Kotlinx Serialization support just add org.jetbrains.kotlinx:kotlinx-serialization-json dependency and configure serialization plugin.

Maven

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>1.8.20</version>

            <dependencies>
                <dependency>
                    <groupId>org.jetbrains.kotlin</groupId>
                    <artifactId>kotlin-maven-serialization</artifactId>
                    <version>1.8.20</version>
                </dependency>
            </dependencies>

            <configuration>
                <compilerPlugins>
                    <plugin>kotlinx-serialization</plugin>
                </compilerPlugins>
            </configuration>

            <executions>
                <execution>
                    <id>compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>io.github.ermadmi78</groupId>
            <artifactId>kobby-maven-plugin</artifactId>
            <version>3.0.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>generate-kotlin</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>

    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-serialization-json</artifactId>
        <version>1.5.0</version>
    </dependency>
</build>

Explicit setup

You can explicitly enable (or disable) Kotlinx Serialization support in the generated code, but you still need to add kotlinx-serialization-json dependency and configure serialization plugin. In addition to the "implicit setup" you can add:

Maven

<plugin>
    <groupId>io.github.ermadmi78</groupId>
    <artifactId>kobby-maven-plugin</artifactId>
    <version>3.0.0</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate-kotlin</goal>
            </goals>
            <configuration>
                <kotlin>
                    <dto>
                        <serialization>
                            <!-- Is Kotlinx Serialization enabled. -->
                            <!-- By default, "true" if "org.jetbrains.kotlinx:kotlinx-serialization-json" -->
                            <!-- artifact is in the project dependencies. -->
                            <enabled>true</enabled>

                            <!-- Name of the class descriptor property for polymorphic serialization. -->
                            <classDiscriminator>__typename</classDiscriminator>

                            <!-- Specifies whether encounters of unknown properties in the input JSON -->
                            <!-- should be ignored instead of throwing SerializationException. -->
                            <ignoreUnknownKeys>true</ignoreUnknownKeys>

                            <!-- Specifies whether default values of Kotlin properties -->
                            <!-- should be encoded to JSON. -->
                            <encodeDefaults>false</encodeDefaults>

                            <!-- Specifies whether resulting JSON should be pretty-printed. -->
                            <prettyPrint>false</prettyPrint>
                        </serialization>
                    </dto>
                </kotlin>
            </configuration>
        </execution>
    </executions>
</plugin>

Kotlinx Serialization entry point

The Kotlinx Serialization entry point in the generated DSL is placed near the DSL context entry point (root file xxx.kt, where xxx is the name of the context). For example, for a context named cinema it would look like this:

cinema.kt

/**
 * Default entry point to work with JSON serialization.
 */
public val cinemaJson: Json = Json {
        classDiscriminator = "__typename"
        ignoreUnknownKeys = true
        encodeDefaults = false
        prettyPrint = false
        serializersModule = SerializersModule {
            polymorphic(EntityDto::class) {
                subclass(FilmDto::class)
                subclass(ActorDto::class)
                subclass(CountryDto::class)
            }
            polymorphic(TaggableDto::class) {
                subclass(FilmDto::class)
                subclass(ActorDto::class)
            }
            polymorphic(NativeDto::class) {
                subclass(FilmDto::class)
                subclass(ActorDto::class)
            }
        }
    }


public fun cinemaContextOf(adapter: CinemaAdapter): CinemaContext = CinemaContextImpl(adapter)

The default adapters use cinemaJson to provide Kotlinx Serialization.

Simple Adapter configuration

Just pass cinemaJson to the Ktor Client content negotiation plugin:

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(cinemaJson)
    }
}

val context = cinemaContextOf(
    CinemaSimpleKtorAdapter(client, "http://localhost:8080/graphql")
)

Composite Adapter configuration

val client = HttpClient(CIO) {
    install(WebSockets)
}

val context = cinemaContextOf(
    CinemaCompositeKtorAdapter(
        client,
        "http://localhost:8080/graphql",
        "ws://localhost:8080/subscriptions"
    )
)

You don't have to do anything because cinemaJson is configured as the default value for the mapper argument:

public open class CinemaCompositeKtorAdapter(
    protected val client: HttpClient,
    protected val httpUrl: String,
    protected val webSocketUrl: String,
    protected val mapper: Json = cinemaJson, // cinemaJson is configured by default!
    // Skipped
) : CinemaAdapter {
    // Skipped
}

Custom serializers

You can configure a custom serializer to any type associated with a scalar. For example, let's define a Date scalar in our schema and associate it with a java.time.LocalDate.

scalar Date

type Query {
    extract: Date!
}

First, we must write custom serializer for java.time.LocalDate:

object LocalDateSerializer : KSerializer<LocalDate> {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("LocalDate", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: LocalDate) =
        encoder.encodeString(value.toString())

    override fun deserialize(decoder: Decoder): LocalDate =
        LocalDate.parse(decoder.decodeString())
}

Second, we must bind java.time.LocalDate to Date scalar and set up LocalDateSerializer for it:

Maven (see scalar mapping)

<plugin>
    <groupId>io.github.ermadmi78</groupId>
    <artifactId>kobby-maven-plugin</artifactId>
    <version>3.0.0</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate-kotlin</goal>
            </goals>
            <configuration>
                <kotlin>
                    <scalars>
                        <Date>
                            <packageName>java.time</packageName>
                            <className>LocalDate</className>
                            <serializer>
                                <packageName>
                                    io.github.ermadmi78.kobby.cinema.api.kobby.kotlin.dto
                                </packageName>
                                <className>LocalDateSerializer</className>
                            </serializer>
                        </Date>
                    </scalars>
                </kotlin>
            </configuration>
        </execution>
    </executions>
</plugin>

Mixing serialization engines

During the development process, it turned out that the Kotlinx Serialization engine does not like type Any at all. To get around this limitation, the plugin replaces type Any in the generated code according to the following rules:

For example, the GraphQL request DTO for Jackson serialization engine looks like this:

public data class CinemaRequest(
    public val query: String,

    @JsonInclude(value = JsonInclude.Include.NON_EMPTY)
    public val variables: Map<String, Any?>? = null,

    @JsonInclude(value = JsonInclude.Include.NON_ABSENT)
    public val operationName: String? = null,
)

But the same DTO for Kotlinx Serialization engine looks like this:

@Serializable
public data class CinemaRequest(
    public val query: String,
    public val variables: JsonObject? = null,
    public val operationName: String? = null,
)

Such a replacement leads to the fact that it is impossible to generate DTO classes that can be serialized using Jackson and Kotlinx Serialization at the same time. Therefore, you will need to choose one of the serialization engines and use only that.

Home

Clone this wiki locally