FilesExpand file tree

 master

/

Coercing.java

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

115 lines (105 loc) · 5.27 KB

 master

/

Coercing.java

Copy path

Top

File metadata and controls

• Code
• Blame

115 lines (105 loc) · 5.27 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

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

package graphql.schema;

import graphql.PublicSpi;

import graphql.language.Value;

import org.jetbrains.annotations.NotNull;

import java.util.Map;

/**

* The Coercing interface is used by {@link graphql.schema.GraphQLScalarType}s to parse and serialise 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> {

/**

* 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 serialisation, 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

*/

O serialize(@NotNull Object dataFetcherResult) throws CoercingSerializeException;

/**

* 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.

*

* @param input is never null

*

* @return a parsed value which is never null

*

* @throws graphql.schema.CoercingParseValueException if value input can't be parsed

*/

@NotNull I parseValue(@NotNull Object input) throws CoercingParseValueException;

/**

* 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.

*

* @param input is never null

*

* @return a parsed value which is never null

*

* @throws graphql.schema.CoercingParseLiteralException if input literal can't be parsed

*/

@NotNull I parseLiteral(@NotNull Object input) throws CoercingParseLiteralException;

/**

* 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.

*

* @param input is never null

* @param variables the resolved variables passed to the query

*

* @return a parsed value which is never null

*

* @throws graphql.schema.CoercingParseLiteralException if input literal can't be parsed

*/

@SuppressWarnings("unused")

default @NotNull I parseLiteral(Object input, Map<String, Object> variables) throws CoercingParseLiteralException {

return parseLiteral(input);

}

/**

* Converts an external input value to a literal (Ast Value).

*

* 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.

*/

default @NotNull Value valueToLiteral(@NotNull Object input) {

throw new UnsupportedOperationException("This is not implemented by this Scalar " + this.getClass());

}

}