graphql-binding

This is a Java library for binding types and interfaces into GraphQL services
using annotations for use with graphql-java.

@GraphQLObject
@GraphQLName("Example")
public class ExampleService {
  @GraphQLField
  public String test() {
    return "example";
  }
}

Features

• Code-first approach to creating GraphQL types via annotations
• Explicit bindings, no bindings of anything unless annotated, manually resolved or a scalar
• Support for object types, enums, interfaces and input types
• Mixins for object types, allowing GraphQL types to be extended
• Conversion of objects into GraphQL types
• Automatic type discovery using an instance of TypeFinder
• Integration with Dependency Injection via InstanceFactory

License

This project is licensed under the Apache License 2.0,
see the file LICENSE and NOTICE for details.

Usage via Maven

This library are available from Maven central:

<dependency>
  <groupId>se.l4.graphql.binding</groupId>
  <artifactId>grapqhl-binding</artifactId>
  <version>3.0.0</version>
</dependency>

Creating a GraphQLSchema

The GraphQLSchema for use with other GraphQL Java tooling, such as
graphql-java-servlet is
created via the type GraphQLBinder.

GraphQLSchema schema = GraphQLBinder.newBinder()
  .withRoot(new RootObject())
  .build();

Setting an instance factory

This library uses an InstanceFactory to resolve non-GraphQL instances, the
default version can create objects with default constructors. Guice integration
is available via an InstanceFactory from commons-guice.

binder.setInstanceFactory(factory);

Automatic discovery of types

Types can be automatically discovered using a TypeFinder instance. If a
TypeFinder is provided it will be queried for types that are annotated with
@GraphQLObject, @GraphQLEnum, @GraphQLInterface and @GraphQLInputObject.
Types annotated with @GraphQLRoot will be created via the current
InstanceFactory and added as root objects.

binder.setTypeFinder(TypeFinder.builder()
  .setInstanceFactory(instanceFactory) // if using a custom instance factory
  .addPackage("root.package.to.scan")
  .build()
)

Defining a GraphQL object

GraphQL object types are created via the @GraphQLObject annotation and
placing @GraphQLField on public fields and methods to make them part of the
object.

@GraphQLObject
public class Pet {
  @GraphQLField
  public final String name;
  public Pet(String name) {
    this.name = name;
  }
  @GraphQLField
  public String fieldViaMethod(
    @GraphQLName("argumentName") String argument
  ) {
    return argument;
  }
}

If a field can not return null it can be annotated with @GraphQLNonNull
to indicate so in the schema. The same is true for arguments. Some types such
as List can also have annotations placed on their inner type:

@GraphQLField
public List<@GraphQLNonNull String> list() {
  ...
}

Defining a GraphQL enum

Enumerations can be defined as regular enums with the annotation @GraphQLEnum.
Both the enum class and individual values in the enum can be annotated with
@GraphQLName and @GraphQLDescription.

@GraphQLEnum
public enum PetType {
  DOG,
  @GraphQLDescription("This is a cat")
  CAT;
}

Query and Mutations via root objects

Root queries and mutations are registered via root objects. These can either
be added via binder.withRoot(instance) or when using type finding by
annotating a type with @GraphQLRoot. Several root objects may exist at the
same time and will all contribute to the initial Query and Mutation types.

public class RootObject {
  @GraphQLField
  public String test() {
    return "Hello World";
  }
}
binder.withRoot(new GraphQLRootTest());

The above root type would expose a single field named test:

query {
  test
}

Use @GraphQLMutation to define mutations:

public class RootObject {
  @GraphQLMutation
  public String createThing(
    @GraphQLName("input") String name
  ) {
    ...
  }
}

Conversion of objects

This library supports the conversion from a non-GraphQL type into a GraphQL
type. This allows one type to return say a Customer and have it mapped into
a CustomerQueryType:

@GraphQLObject
public class CustomersQueryType {
  @GraphQLField
  public Customer getById(String id) {
    // This method can look up and return an instance of Customer
    return ...;
  }
}
@GraphQLObject
@GraphQLName("Customer")
public class CustomerQueryType {
  private final Customer customer;
  @GraphQLFactory
  public CustomerQueryType(@GraphQLSource Customer customer) {
    this.customer = customer;
  }
  @GraphQLField
  @GraphQLDescription("The identifier of the customer")
  public String id() {
    return customer.getId();
  }
}

Add the type to the binder to allow it to register the conversion:

binder.withType(CustomerQueryType.class);

Mixins

Root objects can be used to extend other object types using mixins. This is
useful if one of your modules want to extend a type defined by another module.
Adding @GraphQLMixinField to a method allows it to extend the type defined
by a parameter annotated with @GraphQLSource:

public class RootObject {
  @GraphQLMixinField
  public int extendedMethod(
    @GraphQLSource GraphQLObject source,
    @GraphQLName("argumentName") String argument
  ) {
    ...
  }
}