@PublicSpi public interface Coercing<I,O>
GraphQLScalarType
s to parse and serialise object values.
There are two major responsibilities, result coercion and input coercion.
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.
Input coercion is made out of three different methods parseLiteral(Object)
which converts an literal Ast
into an internal input value, parseValue(Object)
which converts an external input value into an internal one
and valueToLiteral(Object)
which is a translation between an external input value into a literal.
The relationship between these three methods is as follows:
It is required that every valid external input values for parseValue(Object)
is also valid for
valueToLiteral(Object)
and vice versa.
Furthermore the literals returned by valueToLiteral(Object)
are required to be valid for
parseLiteral(Object)
.
Modifier and Type | Method and Description |
---|---|
I |
parseLiteral(@NotNull java.lang.Object input)
Deprecated.
|
default I |
parseLiteral(java.lang.Object input,
java.util.Map<java.lang.String,java.lang.Object> variables)
Deprecated.
|
default I |
parseLiteral(@NotNull Value<?> input,
@NotNull CoercedVariables variables,
@NotNull GraphQLContext graphQLContext,
@NotNull java.util.Locale locale)
Called during query execution to convert a query input AST node into a Java object acceptable for the scalar type.
|
I |
parseValue(@NotNull java.lang.Object input)
Deprecated.
|
default I |
parseValue(@NotNull java.lang.Object input,
@NotNull GraphQLContext graphQLContext,
@NotNull java.util.Locale locale)
Called to resolve an input from a query variable into a Java object acceptable for the scalar type.
|
O |
serialize(@NotNull java.lang.Object dataFetcherResult)
Deprecated.
|
default O |
serialize(@NotNull java.lang.Object dataFetcherResult,
@NotNull GraphQLContext graphQLContext,
@NotNull java.util.Locale locale)
Called to convert a Java object result of a DataFetcher to a valid runtime value for the scalar type.
|
default @NotNull Value |
valueToLiteral(@NotNull java.lang.Object input)
Deprecated.
|
default @NotNull Value<?> |
valueToLiteral(@NotNull java.lang.Object input,
@NotNull GraphQLContext graphQLContext,
@NotNull java.util.Locale locale)
Converts an external input value to a literal (Ast Value).
|
@Deprecated @Nullable O serialize(@NotNull @NotNull java.lang.Object dataFetcherResult) throws CoercingSerializeException
Note : Throw CoercingSerializeException
if there is fundamental
problem during serialisation, don't return null to indicate failure.
Note : You should not allow RuntimeException
s to come out of your serialize method, but rather
catch them and fire them as CoercingSerializeException
instead as per the method contract.
dataFetcherResult
- is never nullCoercingSerializeException
- if value input can't be serialized@Nullable default O serialize(@NotNull @NotNull java.lang.Object dataFetcherResult, @NotNull @NotNull GraphQLContext graphQLContext, @NotNull @NotNull java.util.Locale locale) throws CoercingSerializeException
Note : Throw CoercingSerializeException
if there is fundamental
problem during serialisation, don't return null to indicate failure.
Note : You should not allow RuntimeException
s to come out of your serialize method, but rather
catch them and fire them as CoercingSerializeException
instead as per the method contract.
dataFetcherResult
- is never nullgraphQLContext
- the graphql context in placelocale
- the locale to useCoercingSerializeException
- if value input can't be serialized@Deprecated @NotNull I parseValue(@NotNull @NotNull java.lang.Object input) throws CoercingParseValueException
Note : You should not allow RuntimeException
s to come out of your parseValue method, but rather
catch them and fire them as CoercingParseValueException
instead as per the method contract.
input
- is never nullCoercingParseValueException
- if value input can't be parseddefault I parseValue(@NotNull @NotNull java.lang.Object input, @NotNull @NotNull GraphQLContext graphQLContext, @NotNull @NotNull java.util.Locale locale) throws CoercingParseValueException
Note : You should not allow RuntimeException
s to come out of your parseValue method, but rather
catch them and fire them as CoercingParseValueException
instead as per the method contract.
input
- is never nullgraphQLContext
- the graphql context in placelocale
- the locale to useCoercingParseValueException
- if value input can't be parsed@Deprecated @Nullable I parseLiteral(@NotNull @NotNull java.lang.Object input) throws CoercingParseLiteralException
Value
.
Note : You should not allow RuntimeException
s to come out of your parseLiteral method, but rather
catch them and fire them as CoercingParseLiteralException
instead as per the method contract.
input
- is never nullCoercingParseLiteralException
- if input literal can't be parsed@Deprecated @Nullable default I parseLiteral(java.lang.Object input, java.util.Map<java.lang.String,java.lang.Object> variables) throws CoercingParseLiteralException
Value
.
Note : You should not allow RuntimeException
s to come out of your parseLiteral method, but rather
catch them and fire them as CoercingParseLiteralException
instead as per the method contract.
Many scalar types don't need to implement this method because they don't take AST VariableReference
objects and convert them into actual values. But for those scalar types that want to do this, then this
method should be implemented.
input
- is never nullvariables
- the resolved variables passed to the queryCoercingParseLiteralException
- if input literal can't be parsed@Nullable default I parseLiteral(@NotNull @NotNull Value<?> input, @NotNull @NotNull CoercedVariables variables, @NotNull @NotNull GraphQLContext graphQLContext, @NotNull @NotNull java.util.Locale locale) throws CoercingParseLiteralException
Value
.
Note : You should not allow RuntimeException
s to come out of your parseLiteral method, but rather
catch them and fire them as CoercingParseLiteralException
instead as per the method contract.
Many scalar types don't need to implement this method because they don't take AST VariableReference
objects and convert them into actual values. But for those scalar types that want to do this, then this
method should be implemented.
input
- is never nullvariables
- the resolved variables passed to the querygraphQLContext
- the graphql context in placelocale
- the locale to useNullValue
as inputCoercingParseLiteralException
- if input literal can't be parsed@Deprecated @NotNull default @NotNull Value valueToLiteral(@NotNull @NotNull java.lang.Object input)
IMPORTANT: the argument is validated before by calling parseValue(Object)
.
input
- an external input value@NotNull default @NotNull Value<?> valueToLiteral(@NotNull @NotNull java.lang.Object input, @NotNull @NotNull GraphQLContext graphQLContext, @NotNull @NotNull java.util.Locale locale)
IMPORTANT: the argument is validated before by calling parseValue(Object)
.
input
- an external input valuegraphQLContext
- the graphql context in placelocale
- the locale to use