Query
Overview
Section titled “Overview”actor4j-query connects query languages to actors. Currently it contains one submodule, actor4j-query-graphql, based on graphql-java. It executes GraphQL operations asynchronously and delivers the result to a callback, so an actor (or a pod) never blocks while waiting for a query. A typical use is a PodChildActor or a function pod that answers GraphQL requests of its clients with messages.
The module itself has no dependency on Actor4j - Core. Results are plain Map<String, Object> values (the GraphQL response in its specification format), which can be sent as messages, e.g. wrapped in an ImmutableMap.
<dependency> <groupId>io.actor4j</groupId> <artifactId>actor4j-query-graphql</artifactId> <version>2.5.0</version></dependency>It includes com.graphql-java:graphql-java and org.reactivestreams:reactive-streams transitively.
GraphQLHandler
Section titled “GraphQLHandler”The interface GraphQLHandler (io.actor4j.query.graphql) has two methods: configure(RuntimeWiring.Builder) registers the data fetchers, and execute(Object value, GraphQL graphQL) executes an operation and returns a request id (UUID) at once.
DefaultGraphQLHandler implements execute. A subclass provides the data fetchers and overrides the callbacks:
handleAsyncResponse(UUID requestId, Map<String, Object> responseMap)is called with the result of a query or mutation.handleAsyncSubscription(UUID requestId, Map<String, Object> responseMap)is called for each event of a subscription (when the result is aPublisher).
Both are empty by default. The request id returned by execute is passed to the callbacks, so the answer can be assigned to the request (e.g. as interaction of a message).
public class UserGraphQLHandler extends DefaultGraphQLHandler { protected final UserRepository repository;
public UserGraphQLHandler(UserRepository repository) { this.repository = repository; }
@Override public void configure(RuntimeWiring.Builder builder) { builder.type("Query", typeWiring -> typeWiring.dataFetcher("getUser", env -> { Integer id = env.getArgument("id"); return repository.findById(id); })); }
@Override public void handleAsyncResponse(UUID requestId, Map<String, Object> responseMap) { // e.g. send the response as a message to the requesting actor }}The handler is wired into a graphql-java schema as usual:
String schema = """ type User { id: Int! name: String! email: String } type Query { getUser(id: Int!): User } """;
TypeDefinitionRegistry typeRegistry = new SchemaParser().parse(schema);RuntimeWiring.Builder wiringBuilder = RuntimeWiring.newRuntimeWiring();
UserGraphQLHandler handler = new UserGraphQLHandler(repository);handler.configure(wiringBuilder);
GraphQLSchema graphQLSchema = new SchemaGenerator().makeExecutableSchema(typeRegistry, wiringBuilder.build());GraphQL graphQL = GraphQL.newGraphQL(graphQLSchema).build();
UUID requestId = handler.execute("{ getUser(id: 1) { id name } }", graphQL);Errors of the execution are written to System.err. The response map still contains them under errors, as defined by the GraphQL specification.
Payload
Section titled “Payload”execute accepts the operation in two forms:
- a
Stringwith the GraphQL document - a
Mapwith the keysquery,mutationorsubscription(the document), plus optionalvariables(aMap) andoperationName
handler.execute(Map.of( "query", "query getUser($id: Int!) { getUser(id: $id) { id name email } }", "variables", Map.of("id", 1)), graphQL);Without a document, the operation can be described by operationType (query, mutation or subscription) and operationName (the field of the root type). The document is then generated from the schema. An optional selection sets the selected fields:
handler.execute(Map.of( "operationType", "query", "operationName", "getUser", "variables", Map.of("id", 1), "selection", "id name"), graphQL);If neither a document nor operationType and a known operationName are given, execute throws an IllegalArgumentException.
GraphQLOperationGenerator
Section titled “GraphQLOperationGenerator”GraphQLOperationGenerator.build(schema, operationType, operationName) (and an overload with selection) generates the document used above. All arguments of the field become variables of the operation. Without a selection, all fields without arguments that are not deprecated and have a scalar or enum type are selected. For a union type it selects __typename. For the schema above:
String document = GraphQLOperationGenerator.build(graphQLSchema, "query", "getUser");// query getUser($id: Int!) { getUser(id: $id) { id name email } }It returns null if the operation type or the field does not exist.