Skip to content

Commit 54b5a8d

Browse files
andimarek-atlassianandimarek-atlassian
committed
docs
1 parent a11e68a commit 54b5a8d

File tree

4 files changed

+380
-0
lines changed

4 files changed

+380
-0
lines changed

‎content/documentation/v9/first.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "Welcome"
3+
date: 2018-09-09T12:52:46+10:00
4+
draft: false
5+
tags: [documentation]
6+
weight: 99
7+
---
8+
# Welcome to graphql-java
9+
10+
.. image:: https://avatars1.githubusercontent.com/u/14289921?s=200&v=4
11+
:align: center
12+
:height: 100px
13+
:alt: graphql-java-logo
14+
15+
16+
This is a GraphQL Java implementation based on the [specification](https://github.com/facebook/graphql).
17+
18+
19+
**Status**: Version ``9.0`` is released.
20+
21+
Make sure to check out the [awesome related projects](https://github.com/graphql-java/awesome-graphql-java) built on ``graphql-java``.
22+
23+
24+
25+
## Code of Conduct
26+
27+
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/graphql-java/graphql-java/blob/master/CODE_OF_CONDUCT.md) By contributing to this project (commenting or opening PR/Issues etc) you are agreeing to follow this conduct, so please
28+
take the time to read it.
29+
30+
31+
## Questions and discussions
32+
33+
If you have a question or want to discuss anything else related to this project:
34+
35+
* Feel free to open a new [Issue](https://github.com/graphql-java/graphql-java/issues>).
36+
37+
## License
38+
39+
graphql-java is licensed under the MIT License.
40+
41+
42+
43+

‎content/documentation/v9/instrumentation.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
---
2+
title: "Instrumentation"
3+
date: 2018-09-09T12:52:46+10:00
4+
draft: false
5+
tags: [documentation]
6+
weight: 115
7+
description: Instrumentation
8+
---
9+
# Instrumentation
10+
11+
12+
The ``graphql.execution.instrumentation.Instrumentation`` interface allows you to inject code that can observe the
13+
execution of a query and also change the runtime behaviour.
14+
15+
The primary use case for this is to allow say performance monitoring and custom logging but it could be used for many different purposes.
16+
17+
When you build the ``Graphql`` object you can specify what ``Instrumentation`` to use (if any).
18+
19+
{{< highlight java "linenos=table" >}}
20+
GraphQL.newGraphQL(schema)
21+
.instrumentation(new TracingInstrumentation())
22+
.build();
23+
24+
{{< / highlight >}}
25+
26+
27+
## Custom Instrumentation
28+
29+
An implementation of ``Instrumentation`` needs to implement the "begin" step methods that represent the execution of a graphql query.
30+
31+
Each step must give back a non null ``graphql.execution.instrumentation.InstrumentationContext`` object which will be called back
32+
when the step completes, and will be told that it succeeded or failed with a Throwable.
33+
34+
The following is a basic custom ``Instrumentation`` that measures overall execution time and puts it into a stateful object.
35+
36+
{{< highlight java "linenos=table" >}}
37+
class CustomInstrumentationState implements InstrumentationState {
38+
private Map<String, Object> anyStateYouLike = new HashMap<>();
39+
40+
void recordTiming(String key, long time) {
41+
anyStateYouLike.put(key, time);
42+
}
43+
}
44+
45+
class CustomInstrumentation extends SimpleInstrumentation {
46+
@Override
47+
public InstrumentationState createState() {
48+
//
49+
// instrumentation state is passed during each invocation of an Instrumentation method
50+
// and allows you to put stateful data away and reference it during the query execution
51+
//
52+
return new CustomInstrumentationState();
53+
}
54+
55+
@Override
56+
public InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters) {
57+
long startNanos = System.nanoTime();
58+
return new SimpleInstrumentationContext<ExecutionResult>() {
59+
@Override
60+
public void onCompleted(ExecutionResult result, Throwable t) {
61+
CustomInstrumentationState state = parameters.getInstrumentationState();
62+
state.recordTiming(parameters.getQuery(), System.nanoTime() - startNanos);
63+
}
64+
};
65+
}
66+
67+
@Override
68+
public DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters) {
69+
//
70+
// this allows you to intercept the data fetcher used to fetch a field and provide another one, perhaps
71+
// that enforces certain behaviours or has certain side effects on the data
72+
//
73+
return dataFetcher;
74+
}
75+
76+
@Override
77+
public CompletableFuture<ExecutionResult> instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters) {
78+
//
79+
// this allows you to instrument the execution result some how. For example the Tracing support uses this to put
80+
// the `extensions` map of data in place
81+
//
82+
return CompletableFuture.completedFuture(executionResult);
83+
}
84+
}
85+
86+
{{< / highlight >}}
87+
88+
89+
## Chaining Instrumentation
90+
91+
You can combine multiple ``Instrumentation`` objects together using the ``graphql.execution.instrumentation.ChainedInstrumentation`` class which
92+
accepts a list of ``Instrumentation`` objects and calls them in that defined order.
93+
94+
{{< highlight java "linenos=table" >}}
95+
List<Instrumentation> chainedList = new ArrayList<>();
96+
chainedList.add(new FooInstrumentation());
97+
chainedList.add(new BarInstrumentation());
98+
ChainedInstrumentation chainedInstrumentation = new ChainedInstrumentation(chainedList);
99+
100+
GraphQL.newGraphQL(schema)
101+
.instrumentation(chainedInstrumentation)
102+
.build();
103+
104+
105+
{{< / highlight >}}
106+
107+
108+
109+
## Apollo Tracing Instrumentation
110+
111+
``graphql.execution.instrumentation.tracing.TracingInstrumentation`` is an ``Instrumentation`` implementation that creates tracing information
112+
about the query that is being executed.
113+
114+
It follows the Apollo proposed tracing format defined at `https://github.com/apollographql/apollo-tracing <https://github.com/apollographql/apollo-tracing>`_
115+
116+
A detailed tracing map will be created and placed in the ``extensions`` section of the result.
117+
118+
So given a query like
119+
120+
{{< highlight graphql "linenos=table" >}}
121+
query {
122+
hero {
123+
name
124+
friends {
125+
name
126+
}
127+
}
128+
}
129+
130+
{{< / highlight >}}
131+
132+
It would return a result like
133+
134+
{{< highlight json "linenos=table" >}}
135+
136+
137+
{
138+
"data": {
139+
"hero": {
140+
"name": "R2-D2",
141+
"friends": [
142+
{
143+
"name": "Luke Skywalker"
144+
},
145+
{
146+
"name": "Han Solo"
147+
},
148+
{
149+
"name": "Leia Organa"
150+
}
151+
]
152+
}
153+
},
154+
"extensions": {
155+
"tracing": {
156+
"version": 1,
157+
"startTime": "2017-08-14T23:13:39.362Z",
158+
"endTime": "2017-08-14T23:13:39.497Z",
159+
"duration": 135589186,
160+
"execution": {
161+
"resolvers": [
162+
{
163+
"path": [
164+
"hero"
165+
],
166+
"parentType": "Query",
167+
"returnType": "Character",
168+
"fieldName": "hero",
169+
"startOffset": 105697585,
170+
"duration": 79111240
171+
},
172+
{
173+
"path": [
174+
"hero",
175+
"name"
176+
],
177+
"parentType": "Droid",
178+
"returnType": "String",
179+
"fieldName": "name",
180+
"startOffset": 125010028,
181+
"duration": 20213
182+
},
183+
{
184+
"path": [
185+
"hero",
186+
"friends"
187+
],
188+
"parentType": "Droid",
189+
"returnType": "[Character]",
190+
"fieldName": "friends",
191+
"startOffset": 133352819,
192+
"duration": 7927560
193+
},
194+
{
195+
"path": [
196+
"hero",
197+
"friends",
198+
0,
199+
"name"
200+
],
201+
"parentType": "Human",
202+
"returnType": "String",
203+
"fieldName": "name",
204+
"startOffset": 134105887,
205+
"duration": 6783
206+
},
207+
{
208+
"path": [
209+
"hero",
210+
"friends",
211+
1,
212+
"name"
213+
],
214+
"parentType": "Human",
215+
"returnType": "String",
216+
"fieldName": "name",
217+
"startOffset": 134725922,
218+
"duration": 7016
219+
},
220+
{
221+
"path": [
222+
"hero",
223+
"friends",
224+
2,
225+
"name"
226+
],
227+
"parentType": "Human",
228+
"returnType": "String",
229+
"fieldName": "name",
230+
"startOffset": 134875089,
231+
"duration": 6342
232+
}
233+
]
234+
}
235+
}
236+
}
237+
}
238+
239+
{{< / highlight >}}
240+
241+
## Field Validation Instrumentation
242+
243+
``graphql.execution.instrumentation.fieldvalidation.FieldValidationInstrumentation`` is an ``Instrumentation`` implementation that
244+
can be used to validate fields and their arguments before query execution. If errors are returned during this process then
245+
the query execution is aborted and the errors will be in the query result.
246+
247+
You can make you own custom implementation of ``FieldValidation`` or you can use the ``SimpleFieldValidation`` class
248+
to add simple per field checks rules.
249+
250+
{{< highlight java "linenos=table" >}}
251+
ExecutionPath fieldPath = ExecutionPath.parse("/user");
252+
FieldValidation fieldValidation = new SimpleFieldValidation()
253+
.addRule(fieldPath, new BiFunction<FieldAndArguments, FieldValidationEnvironment, Optional<GraphQLError>>() {
254+
@Override
255+
public Optional<GraphQLError> apply(FieldAndArguments fieldAndArguments, FieldValidationEnvironment environment) {
256+
String nameArg = fieldAndArguments.getFieldArgument("name");
257+
if (nameArg.length() > 255) {
258+
return Optional.of(environment.mkError("Invalid user name", fieldAndArguments));
259+
}
260+
return Optional.empty();
261+
}
262+
});
263+
264+
FieldValidationInstrumentation instrumentation = new FieldValidationInstrumentation(
265+
fieldValidation
266+
);
267+
268+
GraphQL.newGraphQL(schema)
269+
.instrumentation(instrumentation)
270+
.build();
271+
272+
{{< / highlight >}}
273+
274+

‎content/documentation/v9/logging.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: "Logging"
3+
date: 2018-09-09T12:52:46+10:00
4+
draft: false
5+
tags: [documentation]
6+
weight: 115
7+
description: Logging
8+
---
9+
# Logging
10+
11+
Logging is done with `SLF4J <http://www.slf4j.org/>`_. Please have a look at the `Manual <http://www.slf4j.org/manual.html>`_ for details.
12+
The ``graphql-java`` root Logger name is ``graphql``.

‎content/documentation/v9/relay.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: "Relay"
3+
date: 2018-09-09T12:52:46+10:00
4+
draft: false
5+
tags: [documentation]
6+
weight: 115
7+
description: Relay
8+
---
9+
# Relay Support
10+
11+
12+
Very basic support for [Relay](https://github.com/facebook/relay) is included.
13+
14+
**Note**: Relay refers here to "Relay Classic", there is no support for "Relay Modern".
15+
16+
Please look at https://github.com/graphql-java/todomvc-relay-java for a full example project,
17+
18+
Relay send queries to the GraphQL server as JSON containing a ``query`` field and a ``variables`` field. The ``query`` field is a JSON string,
19+
and the ``variables`` field is a map of variable definitions. A relay-compatible server will need to parse this JSON and pass the ``query``
20+
string to this library as the query and the ``variables`` map as the third argument to ``execute`` as shown below.
21+
22+
{{< highlight java "linenos=table" >}}
23+
@RequestMapping(value = "/graphql", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_VALUE)
24+
@ResponseBody
25+
public Object executeOperation(@RequestBody Map body) {
26+
String query = (String) body.get("query");
27+
Map<String, Object> variables = (Map<String, Object>) body.get("variables");
28+
if (variables == null) {
29+
variables = new LinkedHashMap<>();
30+
}
31+
ExecutionResult executionResult = graphql.execute(query, (Object) null, variables);
32+
Map<String, Object> result = new LinkedHashMap<>();
33+
if (executionResult.getErrors().size() > 0) {
34+
result.put("errors", executionResult.getErrors());
35+
log.error("Errors: {}", executionResult.getErrors());
36+
}
37+
result.put("data", executionResult.getData());
38+
return result;
39+
}
40+
41+
42+
{{< / highlight >}}
43+
44+
45+
## Apollo Support
46+
47+
There is no special support for `Apollo <https://github.com/apollographql/apollo-client>`_ included: Apollo works with any schema.
48+
49+
The Controller example shown above works with Apollo too.
50+
51+

0 commit comments

Comments
 (0)