-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Expand file tree
/
Copy pathCoercing.java
More file actions
242 lines (227 loc) · 11.8 KB
/
Coercing.java
File metadata and controls
242 lines (227 loc) · 11.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
package graphql.schema;
import graphql.GraphQLContext;
import graphql.PublicSpi;
import graphql.execution.CoercedVariables;
import graphql.language.Value;
import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;
import java.util.Locale;
import java.util.Map;
import static graphql.Assert.assertNotNull;
/**
* The Coercing interface is used by {@link graphql.schema.GraphQLScalarType}s to parse and serialize object values.
* <p>
* There are two major responsibilities, result coercion and input coercion.
* <p>
* Result coercion is taking a value from a Java object and coercing it into the constraints of the scalar type.
* For example imagine a DateTime scalar, the result coercion would need to take an object and turn it into a
* ISO date or throw an exception if it cant.
* <p>
* Input coercion is made out of three different methods {@link #parseLiteral(Object)} which converts an literal Ast
* into an internal input value, {@link #parseValue(Object)} which converts an external input value into an internal one
* and {@link #valueToLiteral(Object)} which is a translation between an external input value into a literal.
* <br>
* The relationship between these three methods is as follows:
* It is required that every valid external input values for {@link #parseValue(Object)} is also valid for
* {@link #valueToLiteral(Object)}
* and vice versa.
* Furthermore the literals returned by {@link #valueToLiteral(Object)} are required to be valid for
* {@link #parseLiteral(Object)}.
*/
@PublicSpi
public interface Coercing<I, O> {
/**
* This is deprecated and you should implement {@link #serialize(Object, GraphQLContext, Locale)} instead
* <p>
* Called to convert a Java object result of a DataFetcher to a valid runtime value for the scalar type.
* <p>
* Note : Throw {@link graphql.schema.CoercingSerializeException} if there is fundamental
* problem during serialization, don't return null to indicate failure.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your serialize method, but rather
* catch them and fire them as {@link graphql.schema.CoercingSerializeException} instead as per the method contract.
*
* @param dataFetcherResult is never null
*
* @return a serialized value which may be null.
*
* @throws graphql.schema.CoercingSerializeException if value input can't be serialized
*/
@Deprecated(since = "2022-08-22")
default @Nullable O serialize(@NonNull Object dataFetcherResult) throws CoercingSerializeException {
throw new UnsupportedOperationException("The non deprecated version of serialize has not been implemented by this scalar : " + this.getClass());
}
/**
* Called to convert a Java object result of a DataFetcher to a valid runtime value for the scalar type.
* <p>
* Note : Throw {@link graphql.schema.CoercingSerializeException} if there is fundamental
* problem during serialization, don't return null to indicate failure.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your serialize method, but rather
* catch them and fire them as {@link graphql.schema.CoercingSerializeException} instead as per the method contract.
*
* @param dataFetcherResult is never null
* @param graphQLContext the graphql context in place
* @param locale the locale to use
*
* @return a serialized value which may be null.
*
* @throws graphql.schema.CoercingSerializeException if value input can't be serialized
*/
default @Nullable O serialize(@NonNull Object dataFetcherResult, @NonNull GraphQLContext graphQLContext, @NonNull Locale locale) throws CoercingSerializeException {
assertNotNull(dataFetcherResult);
assertNotNull(graphQLContext);
return serialize(dataFetcherResult);
}
/**
* This is deprecated and you should implement {@link #parseValue(Object, GraphQLContext, Locale)} instead
* <p>
* Called to resolve an input from a query variable into a Java object acceptable for the scalar type.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your parseValue method, but rather
* catch them and fire them as {@link graphql.schema.CoercingParseValueException} instead as per the method contract.
* <p>
* Note : if input is explicit/raw value null, input coercion will return null before this method is called
*
* @param input is never null
*
* @return a parsed value which may be null
*
* @throws graphql.schema.CoercingParseValueException if value input can't be parsed
*/
@Deprecated(since = "2022-08-22")
default @Nullable I parseValue(@NonNull Object input) throws CoercingParseValueException {
throw new UnsupportedOperationException("The non deprecated version of parseValue has not been implemented by this scalar : " + this.getClass());
}
/**
* Called to resolve an input from a query variable into a Java object acceptable for the scalar type.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your parseValue method, but rather
* catch them and fire them as {@link graphql.schema.CoercingParseValueException} instead as per the method contract.
*
* Note : if input is explicit/raw value null, input coercion will return null before this method is called
*
* @param input is never null
* @param graphQLContext the graphql context in place
* @param locale the locale to use
*
* @return a parsed value which may be null
*
* @throws graphql.schema.CoercingParseValueException if value input can't be parsed
*/
@Nullable
default I parseValue(@NonNull Object input, @NonNull GraphQLContext graphQLContext, @NonNull Locale locale) throws CoercingParseValueException {
assertNotNull(input);
assertNotNull(graphQLContext);
assertNotNull(locale);
return parseValue(input);
}
/**
* This is deprecated and you should implement {@link #parseLiteral(Value, CoercedVariables, GraphQLContext, Locale)} instead
* <p>
* Called during query validation to convert a query input AST node into a Java object acceptable for the scalar type. The input
* object will be an instance of {@link graphql.language.Value}.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your parseLiteral method, but rather
* catch them and fire them as {@link graphql.schema.CoercingParseLiteralException} instead as per the method contract.
* <p>
* Note : if input is literal {@link graphql.language.NullValue}, input coercion will return null before this method is called
*
* @param input is never null
*
* @return a parsed value which may be null
*
* @throws graphql.schema.CoercingParseLiteralException if input literal can't be parsed
*/
@Deprecated(since = "2022-08-22")
default @Nullable I parseLiteral(@NonNull Object input) throws CoercingParseLiteralException {
throw new UnsupportedOperationException("The non deprecated version of parseLiteral has not been implemented by this scalar : " + this.getClass());
}
/**
* This is deprecated and you should implement {@link #parseLiteral(Value, CoercedVariables, GraphQLContext, Locale)} instead
* <p>
* Called during query execution to convert a query input AST node into a Java object acceptable for the scalar type. The input
* object will be an instance of {@link graphql.language.Value}.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your parseLiteral method, but rather
* catch them and fire them as {@link graphql.schema.CoercingParseLiteralException} instead as per the method contract.
* <p>
* Many scalar types don't need to implement this method because they don't take AST {@link graphql.language.VariableReference}
* objects and convert them into actual values. But for those scalar types that want to do this, then this
* method should be implemented.
*
* Note : if input is literal {@link graphql.language.NullValue}, input coercion will return null before this method is called
*
* @param input is never null
* @param variables the resolved variables passed to the query
*
* @return a parsed value which may be null
*
* @throws graphql.schema.CoercingParseLiteralException if input literal can't be parsed
*/
@SuppressWarnings("unused")
@Deprecated(since = "2022-08-22")
default @Nullable I parseLiteral(Object input, Map<String, Object> variables) throws CoercingParseLiteralException {
return parseLiteral(input);
}
/**
* Called during query execution to convert a query input AST node into a Java object acceptable for the scalar type. The input
* object will be an instance of {@link graphql.language.Value}.
* <p>
* Note : You should not allow {@link java.lang.RuntimeException}s to come out of your parseLiteral method, but rather
* catch them and fire them as {@link graphql.schema.CoercingParseLiteralException} instead as per the method contract.
* <p>
* Many scalar types don't need to implement this method because they don't take AST {@link graphql.language.VariableReference}
* objects and convert them into actual values. But for those scalar types that want to do this, then this
* method should be implemented.
*
* Note : if input is literal {@link graphql.language.NullValue}, input coercion will return null before this method is called
*
* @param input is never null
* @param variables the resolved variables passed to the query
* @param graphQLContext the graphql context in place
* @param locale the locale to use
*
* @return a parsed value which may be null
*
* @throws graphql.schema.CoercingParseLiteralException if input literal can't be parsed
*/
default @Nullable I parseLiteral(@NonNull Value<?> input, @NonNull CoercedVariables variables, @NonNull GraphQLContext graphQLContext, @NonNull Locale locale) throws CoercingParseLiteralException {
assertNotNull(input);
assertNotNull(graphQLContext);
assertNotNull(locale);
return parseLiteral(input, variables.toMap());
}
/**
* This is deprecated and you should implement {@link #valueToLiteral(Object, GraphQLContext, Locale)} instead
* <p>
* Converts an external input value to a literal (Ast Value).
* <p>
* IMPORTANT: the argument is validated before by calling {@link #parseValue(Object)}.
*
* @param input an external input value
*
* @return The literal matching the external input value.
*/
@Deprecated(since = "2022-08-22")
default @NonNull Value valueToLiteral(@NonNull Object input) {
throw new UnsupportedOperationException("The non deprecated version of valueToLiteral has not been implemented by this scalar : " + this.getClass());
}
/**
* Converts an external input value to a literal (Ast Value).
* <p>
* IMPORTANT: the argument is validated before by calling {@link #parseValue(Object)}.
*
* @param input an external input value
* @param graphQLContext the graphql context in place
* @param locale the locale to use
*
* @return The literal matching the external input value.
*/
default @NonNull Value<?> valueToLiteral(@NonNull Object input, @NonNull GraphQLContext graphQLContext, @NonNull Locale locale) {
assertNotNull(input);
assertNotNull(graphQLContext);
assertNotNull(locale);
return valueToLiteral(input);
}
}