Jackon Annotation Configurations and Simpler Query Generation

[lewisenator]

First off, thanks so much for making this excellent library available to the community. This is easily the best Kotlin GraphQL client code generation library. I've found it very configurable and easy to use.

I have a few small ideas that would make this library easier to adopt for my organization:

1. Maven build plugin options to configure the Jackson annotations on the generated DTO classes. Specifically, I want to be able to configure the @JsonTypeInfo annotation's use, include, and property fields, as well as the @JsonInclude annotation's value field.

2. Separate the interface for query/mutation generation from execution. I would like to leverage the generated context impl code to generate queries and mutations without executing the actual query/mutation. As is, the generated context impl requires you to implement an adapter and execute the queries/mutations.

3. Would you allow contributions from the community? These small changes are something I would feel comfortable submitting a pull request for. Perhaps a contributing.md with instructions for the community. setting-guidelines-for-repository-contributors

[ermadmi78]

Hi, @lewisenator

I'm glad you liked the DSL generated by the Kobby Plugin. And thank you for the suggested ideas!

1. As for configuring Jackson annotations, let's detail this topic in the appropriate issue.
2. As for query generation and execution separation - this is a much more difficult question than meets the eye. Let continue discussion about it in comments for this topic.
3. I am glad for every contribution. Thank you! See instructions here. Can you please try to implement Jackson issue for the first step? But with one request - to implement these features for both Maven and Gradle plugins. I have sent you an invitation to join the project. If you have any difficulties during development, I will be glad to help you.

[ermadmi78]

@lewisenator
As for query generation and execution separation.
To execute GraphQL operations Kobby generates context interface that looks by following:

public interface CinemaContext {
  public suspend fun query(__projection: QueryProjection.() -> Unit): Query

  public suspend fun mutation(__projection: MutationProjection.() -> Unit): Mutation

  public fun subscription(__projection: SubscriptionProjection.() -> Unit):
      CinemaSubscriber<Subscription>
}

To provide an ability to instantiate this interface Kobby generates builder function:

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

And also every generated entity implements this interface, to provide an ability to use Kotlin extension functions for smart customization of the generated DSL.

The interface implementation looks like following:

private class CinemaContextImpl(
  private val adapter: CinemaAdapter
) : CinemaContext {
  /**
   * https://youtrack.jetbrains.com/issue/KTIJ-844
   */
  @Suppress("BlockingMethodInNonBlockingContext")
  public override suspend fun query(__projection: QueryProjection.() -> Unit): Query {
    val projectionRef = QueryProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val query = buildString(header.length + body.length + 7) {
      append("query")
      if (header.isNotEmpty()) {
        append('(').append(header).append(')')
      }
      append(body)
    }

    val queryDto: QueryDto = adapter.executeQuery(query, arguments)
    return queryDto.buildEntity(this, projectionRef)
  }

  /**
   * https://youtrack.jetbrains.com/issue/KTIJ-844
   */
  @Suppress("BlockingMethodInNonBlockingContext")
  public override suspend fun mutation(__projection: MutationProjection.() -> Unit): Mutation {
    val projectionRef = MutationProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val mutation = buildString(header.length + body.length + 10) {
      append("mutation")
      if (header.isNotEmpty()) {
        append('(').append(header).append(')')
      }
      append(body)
    }

    val mutationDto: MutationDto = adapter.executeMutation(mutation, arguments)
    return mutationDto.buildEntity(this, projectionRef)
  }

  public override fun subscription(__projection: SubscriptionProjection.() -> Unit):
      CinemaSubscriber<Subscription> {
    val projectionRef = SubscriptionProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val subscription = buildString(header.length + body.length + 14) {
      append("subscription")
      if (header.isNotEmpty()) {
        append('(').append(header).append(')')
      }
      append(body)
    }

    return CinemaSubscriber<Subscription> {
      adapter.executeSubscription(subscription, arguments) {
        val receiver = CinemaReceiver<Subscription> {
          val subscriptionDto: SubscriptionDto = receive()
          subscriptionDto.buildEntity(this@CinemaContextImpl, projectionRef)
        }
        it.invoke(receiver)
      }
    }
  }
}

Could you please describe your suggestions in more detail?

[lewisenator]

I want to be able to more easily generate a query or mutation without executing it and without providing an Adapter.

Right now, I'm doing something like this:

<configuration>
    <kotlin>
        <impl>
            <internal>false</internal>
        </impl>
    </kotlin>
</configuration>

data class ExecutableQuery(
    var query: String, 
    var variables: MutableMap<String, Any> = mutableMapOf()
)

fun generateQuery(__projection: QueryProjection.() -> Unit): ExecutableQuery {
    // copied from the generated context impl
    val projectionRef = QueryProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder()
    val arguments: MutableMap<String, Any> = mutableMapOf()

    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val query = buildString {
        append("query")
        if (header.isNotEmpty()) {
            append('(').append(header).append(')')
        }
        append(body)
    }
    
    // returns the query and args without executing
    return ExecutableQuery(query, arguments)
}

It would be easier if there was a public QueryGenerator and MutationGenerator interface. (Maybe subscription as well?)

Something like this:

Public Interfaces

public interface CinemaQueryGenerator {
  public suspend fun generateQuery(__projection: QueryProjection.() -> Unit): ExecutableQuery
}

public interface CinemaMutationGenerator {
  public suspend fun generateMutation(__projection: MutationProjection.() -> Unit): ExecutableMutation
}

// no changes to the current context public interface
public interface CinemaContext {
  public suspend fun query(__projection: QueryProjection.() -> Unit): Query

  public suspend fun mutation(__projection: MutationProjection.() -> Unit): Mutation

  public fun subscription(__projection: SubscriptionProjection.() -> Unit):
      CinemaSubscriber<Subscription>
} 

Builder Functions

public fun cinemaQueryGenerator(): CinemaQueryGenerator = CinemaQueryGeneratorImpl()

public fun cinemaMutationGenerator(): CinemaMutationGenerator = CinemaMutationGeneratorImpl()

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

Implementations

private class CinemaQueryGeneratorImpl() : CinemaQueryGenerator {
  public override suspend fun generateQuery(__projection: QueryProjection.() -> Unit): ExecutableQuery {
    val projectionRef = QueryProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val query = buildString(header.length + body.length + 7) {
      append("query")
      if (header.isNotEmpty()) {
        append('(').append(header).append(')')
      }
      append(body)
    }

    return ExecutableQuery(query, arguments)
  }
}

private class CinemaContextImpl(
  private val adapter: CinemaAdapter,
  private val queryGenerator: CinemaQueryGenerator = CinemaQueryGeneratorImpl(),
  private val mutationGenerator: CinemaMutationGenerator = CinemaMutationGeneratorImpl()
) : CinemaContext {
  
  /**
   * https://youtrack.jetbrains.com/issue/KTIJ-844
   */
  @Suppress("BlockingMethodInNonBlockingContext")
  public override suspend fun query(__projection: QueryProjection.() -> Unit): Query {
    val executableQuery = queryGenerator.generateQuery(__projection)
    val queryDto: QueryDto = adapter.executeQuery(executableQuery)
    return queryDto.buildEntity(this, projectionRef)
  }

  // ... rest of context impl ...

}

[ermadmi78]

Great idea, Kenneth! Thank you!

I would only replace ExecutableQuery and ExecutableMutation classes with kotlin.Pair<String, Map<String, Any>> so as not to create additional entities. Moreover, the Pair<String, Map<String, Any>> is immutable, which allows us to safely publish it among threads.
And in addition to the CinemaQueryGenerator and CinemaMutationGenerator interfaces, I would generate CinemaSubscriptionGenerator to enable plugin users to build subscriptions.

Let's implement it.

[ermadmi78]

An alternative option is to join CinemaQueryGenerator, CinemaMutationGenerator and CinemaSubscriptionGenerator to a single interface CinemaBuilder (it seems to me that the word "builder" better reflects the purpose of the interface than the word "generator"):

public fun cinemaContextOf(adapter: CinemaAdapter): CinemaContext = CinemaContextImpl(adapter)
public fun cinemaBuilderOf(): CinemaBuilder = CinemaBuilderImpl()

public interface CinemaContext {
  public suspend fun query(__projection: QueryProjection.() -> Unit): Query
  public suspend fun mutation(__projection: MutationProjection.() -> Unit): Mutation
  public fun subscription(__projection: SubscriptionProjection.() -> Unit):
      CinemaSubscriber<Subscription>
} 

public interface CinemaBuilder {
  public fun buildQuery(__projection: QueryProjection.() -> Unit): Pair<String, Map<String, Any>>
  public fun buildMutation(__projection: MutationProjection.() -> Unit): Pair<String, Map<String, Any>>
  public fun buildSubscription(__projection: SubscriptionProjection.() -> Unit): Pair<String, Map<String, Any>>
}

This API design will be "symmetrical" with respect to the existing one - the CinemaBuilder interface is very similar to the CinemaContext interface.

Separately, I note that functions buildQuery, buildMutation and buildSubscription must not be "suspend". They do not interact with the server over the network, but simply build a query string.

[ermadmi78]

Stop! I figured out how to do it :) Now I will prepare a working example!

[ermadmi78]

I posted a working example here (the branch "builder" of "Kobby Gradle Example" project). Just execute "main" function to see example output:

fun buildCinemaQuery(__projection: QueryProjection.() -> Unit): Pair<String, Map<String, Any>> {
    val projectionRef = QueryProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val query = buildString(header.length + body.length + 7) {
        append("query")
        if (header.isNotEmpty()) {
            append('(').append(header).append(')')
        }
        append(body)
    }

    return query to arguments
}

fun buildCinemaMutation(__projection: MutationProjection.() -> Unit): Pair<String, Map<String, Any>> {
    val projectionRef = MutationProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val mutation = buildString(header.length + body.length + 10) {
        append("mutation")
        if (header.isNotEmpty()) {
            append('(').append(header).append(')')
        }
        append(body)
    }

    return mutation to arguments
}

fun buildCinemaSubscription(__projection: SubscriptionProjection.() -> Unit): Pair<String, Map<String, Any>> {
    val projectionRef = SubscriptionProjectionImpl().apply(__projection)

    val header = StringBuilder()
    val body = StringBuilder(64)
    val arguments: MutableMap<String, Any> = mutableMapOf()
    projectionRef.___innerBuild(setOf(), header, body, arguments)

    val subscription = buildString(header.length + body.length + 14) {
        append("subscription")
        if (header.isNotEmpty()) {
            append('(').append(header).append(')')
        }
        append(body)
    }

    return subscription to arguments
}

fun main() {
    val (query, queryArgs) = buildCinemaQuery {
        films {
            genre = Genre.COMEDY
            genre()
            actors {
                limit = -1
                gender()
            }
        }
    }

    println("Query: $query")
    println("Query arguments: $queryArgs")

    val (mutation, mutationArgs) = buildCinemaMutation {
        createCountry("My Country")
    }

    println("Mutation: $mutation")
    println("Mutation arguments: $mutationArgs")

    val (subscription, subscriptionArgs) = buildCinemaSubscription {
        filmCreated(countryId = 7L) {
            genre()
        }
    }
    println("Subscription: $subscription")
    println("Subscription arguments: $subscriptionArgs")
}

[ermadmi78]

@lewisenator, I have created a builder issue. Could you please implement this task if you do not mind the API design I proposed?

[lewisenator]

@ermadmi78 Great! Yeah, I like your proposed design changes. I'll start working on this. Thanks!

[ermadmi78]

@lewisenator I have posted example with your builders in the tutorial. Looks great! :)

[lewisenator]

Awesome! Thanks Dmitry!