Maven

Plugin Documentation

Goals available for this plugin:

Goal Description
graphql:generateClientCode

The generateClientCode Maven goal (and Gradle task) generates the java code from one or more GraphQL schemas. It allows to work in Java with graphQL, in a schema first approach.

It generates a class for each query, mutation and subscription type. These classes contain the methods to call the queries, mutations and subscriptions. That is: to execute a query against the GraphQL server, you just have to call one of these methods. It also generates the POJOs from the GraphQL schema. The GraphQL response is stored in these POJOs, for an easy and standard use in Java.

You'll find more info in the tutorials: take a look at the Maven client tutorial or the Gradle client tutorial
graphql:generateGraphQLSchema

The generateGraphQLSchema goal generates GraphQL schema, based on the source GraphQL schemas, and possibly containing additional stuff, like the Relay connection objects.

It can be used to:
  • Generate several GraphQL schema files into one file, for instance with additional schema files that would use the extend GraphQL keyword
  • Reformat the schema file
  • Generate the GraphQL schema with the Relay Connection stuff (Node interface, XxxEdge and XxxConnection types), thanks to the addRelayConnections plugin parameter.

This goal is, by default, attached to the Initialize maven phase, to be sure that the GraphQL schema are generated before the code generation would need it, if relevant.

graphql:generatePojo

The generatePojo goal generates all the java objects that match the provided GraphQL schema. It allows to work in Java with graphQL, in a schema first approach.

This goal generates:
  • One java interface for each GraphQL `union` and `interface`
  • One java class for each GraphQL `type` and `input` type, including the query, mutation and subscription (if any). If the GraphQL type implements an interface, then its java class implements this same interface
  • One java enum for each GraphQL enum

Every class, interface and their attributes are marked with the annotation from the GraphQL annotation package. This allows to retrieve the GraphQL information for every class, interface and attribute, at runtime.

It can run in two modes (see the mode plugin parameter for more information):

  • server: In the server mode, only the GraphQL annotation are added. You can add the JPA annotation, with the generateJPAAnnotation plugin parameter set to true.
  • client: The client mode is the default one. This mode generates the same POJO as in server mode, with the addition of the Jackson annotations. These annotations allows to serialize and unserialize the GraphQL POJO to and from JSON. And the CustomJacksonDeserializers utility class is generated, that allows to deserialize custom scalars and arrays.

To avoid to add plugin dependencies, the recommended value for copyRuntimeSources is true. Please note that the default value changed from true to false since 2.0.

In other word, since 2.0, it is a recommended to set the copyRuntimeSources plugin parameter to true.

graphql:generateServerCode

The generateServerCode Maven goal (and Gradle task) generates the java code for an almost ready to start GraphQL server. The developer has only to develop request to the data.

The java code is generated from one or more GraphQL schemas. It allows to work in Java with graphQL, in a schema first approach. These items are generated:

  • the main method (in a jar project) or the main servlet (in a war project)
  • All the GraphQL wiring, based on graphql-java-spring, itself being build on top of graphql-java
  • All the POJOs, that contain the incoming request contents. The request response is written by the user code into these POJO, and the plugin take care of mapping them into the server response.
  • An option allows to annotate the POJOs with the standard JPA annotations, to make it easy to link with a database. Please note that a
  • All the interfaces for the com.graphql_java_generator.plugin.language.DataFetchersDelegate (named providers in the graphql.org presentation) that the server needs to implement

The specific code that needs to be implemented is the access to the Data: your database, other APIs or web services, or any kind of storage you may have. This is done by implementing the interfaces for the com.graphql_java_generator.plugin.language.DataFetchersDelegate into a Spring component, that is:

  • Create a class for each generated com.graphql_java_generator.plugin.language.DataFetchersDelegate interface
  • Make it implement the relevant com.graphql_java_generator.plugin.language.DataFetchersDelegate interface
  • Mark it with the org.springframework.stereotype.Component annotation

And you're done! :)

You'll find more info in the tutorials: take a look at the Maven server tutorial or the Gradle server tutorial

graphql:graphql

This goal is deprecated. The graphql goal generates the java code from one or more GraphQL schemas. It allows to work in Java with graphQL, in a schema first approach.

It will be maintained in the future 2.x versions. The generateClientCode and generateServerCode should be used instead.
The graphql goal has two main modes:
  • client mode: it does the same jobs as the generateClientCode goal. It generates a class for each query, mutation and subscription type. These classes contain the methods to call the queries, mutations and subscriptions. That is: to execute a query against the GraphQL server, you just have to call one of this method. It also generates the POJOs from the GraphQL schema. The GraphQL response is stored in these POJOs, for an easy and standard use in Java.
  • server mode: it does the same jobs as the generateServerCode goal. It generates the whole heart of the GraphQL server. The developer has only to develop request to the data. That is the main method (in a jar project) or the main server (in a war project), and all the Spring wiring, based on graphql-java-spring, itself being build on top of graphql-java. It also generates the POJOs. An option allows to annotate them with the standard JPA annotations, to make it easy to link with a database. This goal generates the interfaces for the DataFetchersDelegate (often named providers) that the server needs to implement

System Requirements

The following specifies the minimum requirements to run this Maven plugin:

Maven 2.0
JDK 8

Usage

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>com.graphql-java-generator</groupId>
          <artifactId>graphql-maven-plugin</artifactId>
          <version>2.5</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>com.graphql-java-generator</groupId>
        <artifactId>graphql-maven-plugin</artifactId>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

For more information, see "Guide to Configuring Plug-ins"