This module implements a GraphQL Java Servlet. It also supports Relay.js, Apollo and OSGi out of the box.
You can download releases from maven central:
repositories {
mavenCentral()
}
dependencies {
compile 'com.graphql-java:graphql-java-servlet:6.0.0'
}<dependency>
<groupId>com.graphql-java</groupId>
<artifactId>graphql-java-servlet</artifactId>
<version>6.0.0</version>
</dependency>The servlet supports the following request formats:
- GET request to
../schema.json: Get the result of an introspection query. - GET request with query parameters (query only, no mutation):
- 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 servlet listeners to an existing servlet. These listeners provide hooks into query execution (before, success, failure, and finally) and servlet execution (before, success, error, and finally):
servlet.addListener(new GraphQLServletListener() {
@Override
GraphQLServletListener.RequestCallback onRequest(HttpServletRequest request, HttpServletResponse response) {
return new GraphQLServletListener.RequestCallback() {
@Override
void onSuccess(HttpServletRequest request, HttpServletResponse response) {
}
@Override
void onError(HttpServletRequest request, HttpServletResponse response, Throwable throwable) {
}
@Override
void onFinally(HttpServletRequest request, HttpServletResponse response) {
}
}
}
@Override
GraphQLServletListener.OperationCallback onOperation(GraphQLContext context, String operationName, String query, Map<String, Object> variables) {
return new GraphQLServletListener.OperationCallback() {
@Override
void onSuccess(GraphQLContext context, String operationName, String query, Map<String, Object> variables, Object data) {
}
@Override
void onError(GraphQLContext context, String operationName, String query, Map<String, Object> variables, Object data, List<GraphQLError> errors) {
}
@Override
void onFinally(GraphQLContext context, String operationName, String query, Map<String, Object> variables, Object data) {
}
}
}
})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.
Query batching is supported, no configuration required.
To use the servlet with Spring Framework, either use the Spring Boot starter or simply define a ServletRegistrationBean 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:
And here is a sample src/main/feature/feature.xml file to add some dependencies on other features:
Here's an example of a GraphQL provider that implements three interfaces at the same time.
It is possible to use dataloaders in a request scope by customizing GraphQLContextBuilder. And instantiating a new DataLoaderRegistry for each GraphQLContext. For eg:
public class CustomGraphQLContextBuilder implements GraphQLContextBuilder {
private final DataLoader userDataLoader;
public CustomGraphQLContextBuilder(DataLoader userDataLoader) {
this.userDataLoader = userDataLoader;
}
@Override
public GraphQLContext build(HttpServletRequest req) {
GraphQLContext context = new GraphQLContext(req);
context.setDataLoaderRegistry(buildDataLoaderRegistry());
return context;
}
@Override
public GraphQLContext build() {
GraphQLContext context = new GraphQLContext();
context.setDataLoaderRegistry(buildDataLoaderRegistry());
return context;
}
@Override
public GraphQLContext build(HandshakeRequest request) {
GraphQLContext context = new GraphQLContext(request);
context.setDataLoaderRegistry(buildDataLoaderRegistry());
return context;
}
private DataLoaderRegistry buildDataLoaderRegistry() {
DataLoaderRegistry dataLoaderRegistry = new DataLoaderRegistry();
dataLoaderRegistry.register("userDataLoader", userDataLoader);
return dataLoaderRegistry;
}
}It is then possible to access the DataLoader in the resolvers by accessing the [DataLoaderRegistry] from context. For eg:
public CompletableFuture<String> getEmailAddress(User user, DataFetchingEnvironment dfe) { // User is the graphQL type
final DataLoader<String, UserDetail> userDataloader =
dfe.getContext().getDataLoaderRegistry().get().getDataLoader("userDataLoader"); // UserDetail is the data that is loaded
return userDataloader.load(User.getName())
.thenApply(userDetail -> userDetail != null ? userDetail.getEmailAddress() : null);
}