This module implements a GraphQL Java Servlet. It also supports Relay.js and OSGi out of the box.

You can download releases from maven central:

repositories { mavenCentral() } dependencies { compile 'com.graphql-java:graphql-java-servlet:2.1.0' }

<dependency> <groupId>com.graphql-java</groupId> <artifactId>graphql-java-servlet</artifactId> <version>2.1.0</version> </dependency>

The servlet supports the following request formats:

• GET request with query parameters:
  • query
  • operationName (optional)
  • variables (optional)
• POST body JSON object with fields:
  • query
  • operationName (optional)
  • variables (optional)
• POST multipart part named "graphql" containing JSON object with fields:
  • query
  • operationName (optional)
  • variables (optional)
• POST multipart parts named "query", "operationName" (optional), and "variables" (optional)

The simplest form of the servlet takes a graphql-java GraphQLSchema and an ExecutionStrategy:

GraphQLServlet servlet = new SimpleGraphQLServlet(schema, executionStrategy); // or GraphQLServlet servlet = new SimpleGraphQLServlet(schema, executionStrategy, operationListeners, servletListeners);

You can also add operation listeners and servlet listeners to an existing servlet. These listeners provide hooks into query execution (before, on success, and on failure) and servlet execution (before, on error, and finally):

servlet.addOperationListener(new GraphQLOperationListener() { @Override void beforeGraphQLOperation(GraphQLContext context, String operationName, String query, Map<String, Object> variables) { } @Override void onSuccessfulGraphQLOperation(GraphQLContext context, String operationName, String query, Map<String, Object> variables, Object data) { } @Override void onFailedGraphQLOperation(GraphQLContext context, String operationName, String query, Map<String, Object> variables, Object data, List<GraphQLError> errors) { } }) servlet.addServletListener(new GraphQLServletListener() { @Override void onStart(HttpServletRequest request, HttpServletResponse response) { } @Override void onError(HttpServletRequest request, HttpServletResponse response, Throwable throwable) { } @Override void onFinally(HttpServletRequest request, HttpServletResponse response) { } })

Relay.js support is provided by the EnhancedExecutionStrategy of graphql-java-annotations. You MUST pass this execution strategy to the servlet for Relay.js support.

This is the default execution strategy for the OsgiGraphQLServlet, and must be added as a dependency when using that servlet.

To use the servlet with Spring Framework, simply define a ServletRegistrationBean bean in a web app:

@Bean ServletRegistrationBean graphQLServletRegistrationBean(GraphQLSchema schema, ExecutionStrategy executionStrategy, List<GraphQLOperationListener> operationListeners) { return new ServletRegistrationBean(new SimpleGraphQLServlet(schema, executionStrategy, operationListeners), "/graphql"); }

The OsgiGraphQLServlet uses a "provider" model to supply the servlet with the required objects:

• GraphQLQueryProvider: Provides query fields to the GraphQL schema.
• GraphQLMutationProvider: Provides mutation fields to the GraphQL schema.
• GraphQLTypesProvider: Provides type information to the GraphQL schema.
• ExecutionStrategyProvider: Provides an execution strategy for running each query.
• GraphQLContextBuilder: Builds a context for running each query.

You can now find some example on how to use graphql-java-servlet.

The OSGi examples use Maven as a build tool because it requires plugins that are not (yet) available for Gradle. Therefore you will need Maven 3.2+.

You can build the OSGi examples sub-projects by simply executing the following command from the examples/osgi directory:

mvn clean install 

This will generate a complete Apache Karaf distribution in the following files:

 examples/osgi/apache-karaf-package/target/graphql-java-servlet-osgi-examples-apache-karaf-package-VERSION.tar.gz(.zip) 

You can simply uncompress this file and launch the OSGi server using the command from the uncompressed directory:

bin/karaf 

You should then be able to access the GraphQL endpoint at the following URL once the server is started:

http://localhost:8181/graphql/schema.json 

If you see the JSON result of an introspection query, then all is ok. If not, check the data/log/karaf.log file for any errors.

We also provide a script file to do all of the building and running at once (only for Linux / MacOS ):

./buildAndRun.sh 

You can use the graphql-java-servlet as part of an Apache Karaf feature, as you can see in the example project here:

• pom.xml

And here is a sample src/main/feature/feature.xml file to add some dependencies on other features:

• feature.xml

Here's an example of a GraphQL provider that implements three interfaces at the same time.

• ExampleGraphQLProvider