8000 Reviewed exceptions in graphql-java (#752) · aeonve/graphql-java@9ce58dd · GitHub
[go: up one dir, main page]
Skip to content

Commit 9ce58dd

Browse files
bbakermanbbakerman
authored
Reviewed exceptions in graphql-java (graphql-java#752)
* Reviewed exceptions in graphql-java * Added rst doco and the ability to preview documentation locally * Clarified text around what constitutes an exception
1 parent 7bfd4fd commit 9ce58dd

23 files changed

+423
-65
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ classes
88
_site
99
generated-src/
1010
out
11+
docs/_build/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python -msphinx
7+
SPHINXPROJ = graphql-java
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# graphql-java documentation build configuration file, created by
4+
# sphinx-quickstart on Wed Oct 4 19:10:27 2017.
5+
#
6+
# This file is execfile()d with the current directory set to its
7+
# containing dir.
8+
#
9+
# Note that not all possible configuration values are present in this
10+
# autogenerated file.
11+
#
12+
# All configuration values have a default; values that are commented out
13+
# serve to show the default.
14+
15+
# If extensions (or modules to document with autodoc) are in another directory,
16+
# add these directories to sys.path here. If the directory is relative to the
17+
# documentation root, use os.path.abspath to make it absolute, like shown here.
18+
#
19+
# import os
20+
# import sys
21+
# sys.path.insert(0, os.path.abspath('.'))
22+
23+
24+
# -- General configuration ------------------------------------------------
25+
26+
# If your documentation needs a minimal Sphinx version, state it here.
27+
#
28+
# needs_sphinx = '1.0'
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = []
34+
35+
# Add any paths that contain templates here, relative to this directory.
36+
templates_path = ['_templates']
37+
38+
# The suffix(es) of source filenames.
39+
# You can specify multiple suffix as a list of string:
40+
#
41+
# source_suffix = ['.rst', '.md']
42+
source_suffix = '.rst'
43+
44+
# The master toctree document.
45+
master_doc = 'index'
46+
47+
# General information about the project.
48+
project = u'graphql-java'
49+
copyright = u'2017, Brad Baker'
50+
author = u'Brad Baker'
51+
52+
# The version info for the project you're documenting, acts as replacement for
53+
# |version| and |release|, also used in various other places throughout the
54+
# built documents.
55+
#
56+
# The short X.Y version.
57+
version = u'current'
58+
# The full version, including alpha/beta/rc tags.
59+
release = u'current'
60+
61+
# The language for content autogenerated by Sphinx. Refer to documentation
62+
# for a list of supported languages.
63+
#
64+
# This is also used if you do content translation via gettext catalogs.
65+
# Usually you set "language" from the command line for these cases.
66+
language = 'java'
67+
68+
# List of patterns, relative to source directory, that match files and
69+
# directories to ignore when looking for source files.
70+
# This patterns also effect to html_static_path and html_extra_path
71+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
72+
73+
# The name of the Pygments (syntax highlighting) style to use.
74+
pygments_style = 'sphinx'
75+
76+
# If true, `todo` and `todoList` produce output, else they produce nothing.
77+
todo_include_todos = False
78+
79+
80+
# -- Options for HTML output ----------------------------------------------
81+
82+
# The theme to use for HTML and HTML Help pages. See the documentation for
83+
# a list of builtin themes.
84+
#
85+
html_theme = 'alabaster'
86+
87+
# Theme options are theme-specific and customize the look and feel of a theme
88+
# further. For a list of options available for each theme, see the
89+
# documentation.
90+
#
91+
# html_theme_options = {}
92+
93+
# Add any paths that contain custom static files (such as style sheets) here,
94+
# relative to this directory. They are copied after the builtin static files,
95+
# so a file named "default.css" will overwrite the builtin "default.css".
96+
html_static_path = ['_static']
97+
98+
# Custom sidebar templates, must be a dictionary that maps document names
99+
# to template names.
100+
#
101+
# This is required for the alabaster theme
102+
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
103+
html_sidebars = {
104+
'**': [
105+
'about.html',
106+
'navigation.html',
107+
'relations.html', # needs 'show_related': True theme option to display
108+
'searchbox.html',
109+
'donate.html',
110+
]
111+
}
112+
113+
114+
# -- Options for HTMLHelp output ------------------------------------------
115+
116+
# Output file base name for HTML help builder.
117+
htmlhelp_basename = 'graphql-javadoc'
118+
119+
120+
# -- Options for LaTeX output ---------------------------------------------
121+
122+
latex_elements = {
123+
# The paper size ('letterpaper' or 'a4paper').
124+
#
125+
# 'papersize': 'letterpaper',
126+
127+
# The font size ('10pt', '11pt' or '12pt').
128+
#
129+
# 'pointsize': '10pt',
130+
131+
# Additional stuff for the LaTeX preamble.
132+
#
133+
# 'preamble': '',
134+
135+
# Latex figure (float) alignment
136+
#
137+
# 'figure_align': 'htbp',
138+
}
139+
140+
# Grouping the document tree into LaTeX files. List of tuples
141+
# (source start file, target name, title,
142+
# author, documentclass [howto, manual, or own class]).
143+
latex_documents = [
144+
(master_doc, 'graphql-java.tex', u'graphql-java Documentation',
145+
u'Brad Baker', 'manual'),
146+
]
147+
148+
149+
# -- Options for manual page output ---------------------------------------
150+
151+
# One entry per manual page. List of tuples
152+
# (source start file, name, description, authors, manual section).
153+
man_pages = [
154+
(master_doc, 'graphql-java', u'graphql-java Documentation',
155+
[author], 1)
156+
]
157+
158+
159+
# -- Options for Texinfo output -------------------------------------------
160+
161+
# Grouping the document tree into Texinfo files. List of tuples
162+
# (source start file, target name, title, author,
163+
# dir menu entry, description, category)
164+
texinfo_documents = [
165+
(master_doc, 'graphql-java', u'graphql-java Documentation',
166+
author, 'graphql-java', 'One line description of project.',
167+
'Miscellaneous'),
< 3360 code>168+
]
169+
170+
171+

‎docs/exceptions.rst‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Runtime Exceptions
2+
==================
3+
4+
5+
Runtime exceptions can be thrown by the graphql engine if certain exceptional situations are encountered. The following
6+
are a list of the exceptions that can be thrown all the way out of a ``graphql.execute(...)`` call.
7+
8+
These are not graphql errors in execution but rather totally unacceptable conditions in which to execute a graphql query.
9+
10+
- `graphql.schema.CoercingSerializeException`
11+
12+
is thrown when a value cannot be serialised by a Scalar type, for example
13+
a String value being coerced as an Int.
14+
15+
16+
- `graphql.schema.CoercingParseValueException`
17+
18+
is thrown when a value cannot be parsed by a Scalar type, for example
19+
a String input value being parsed as an Int.
20+
21+
22+
- `graphql.execution.UnresolvedTypeException`
23+
24+
is thrown if a graphql.schema.TypeResolver` fails to provide a concrete
25+
object type given a interface or union type.
26+
27+
28+
- `graphql.execution.NonNullableValueCoercedAsNullException`
29+
30+
is thrown if a non null variable argument is coerced as a
31+
null value during execution.
32+
33+
34+
- `graphql.execution.InputMapDefinesTooManyFieldsException`
35+
36+
is thrown if a map used for an input type object contains
37+
more keys than is defined in that input type.
38+
39+
40+
- `graphql.schema.validation.InvalidSchemaException`
41+
42+
is thrown if the schema is not valid when built via
43+
graphql.schema.GraphQLSchema.Builder#build()`
44+
45+
46+
- `graphql.GraphQLException`
47+
48+
is thrown as a general purpose runtime exception, for example if the code cant
49+
access a named field when examining a POJO, it is analogous to a RuntimeException if you will.
50+
51+
52+
- `graphql.AssertException`
53+
54+
is thrown as a low level code assertion exception for truly unexpected code conditions, things we assert
55+
should never happen in practice.
56+

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ graphql-java is licensed under the MIT License.
4444
getting_started
4545
schema
4646
execution
47+
exceptions
4748
batching
4849
instrumentation
4950
relay

‎docs/readme.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
2+
To build the documentation locally do the following :
3+
4+
```
5+
> pip install sphinx sphinx-autobuild
6+
> cd docs
7+
> make html
8+
```
9+
10+
This will create the output in _build/html so on Mac you should be able to
11+
12+
```
13+
> open _build/html/index.html
14+
```
15+
which will open a browser with the rendered documentation

‎src/main/java/graphql/GraphQL.java‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,47 @@
4242
*
4343
* Building this object is very cheap and can be done on each execution if necessary. Building the schema is often not
4444
* as cheap, especially if its parsed from graphql IDL schema format via {@link graphql.schema.idl.SchemaParser}.
45+
*
46+
* The data for a query is returned via {@link ExecutionResult#getData()} and any errors encountered as placed in
47+
* {@link ExecutionResult#getErrors()}.
48+
*
49+
* <h2>Runtime Exceptions</h2>
50+
*
51+
* Runtime exceptions can be thrown by the graphql engine if certain situations are encountered. These are not errors
52+
* in execution but rather totally unacceptable conditions in which to execute a graphql query.
53+
* <ul>
54+
* <li>{@link graphql.schema.CoercingSerializeException} - is thrown when a value cannot be serialised by a Scalar type, for example
55+
* a String value being coerced as an Int.
56+
* </li>
57+
*
58+
* <li>{@link graphql.schema.CoercingParseValueException} - is thrown when a value cannot be parsed by a Scalar type, for example
59+
* a String input value being parsed as an Int.
60+
* </li>
61+
*
62+
* <li>{@link graphql.execution.UnresolvedTypeException} - is thrown if a {@link graphql.schema.TypeResolver} fails to provide a concrete
63+
* object type given a interface or union type.
64+
* </li>
65+
*
66+
* <li>{@link graphql.execution.NonNullableValueCoercedAsNullException} - is thrown if a non null variable argument is coerced as a
67+
* null value during execution.
68+
* </li>
69+
*
70+
* <li>{@link graphql.execution.InputMapDefinesTooManyFieldsException} - is thrown if a map used for an input type object contains
71+
* more keys than is defined in that input type.
72+
* </li>
73+
*
74+
* <li>{@link graphql.schema.validation.InvalidSchemaException} - is thrown if the schema is not valid when built via
75+
* {@link graphql.schema.GraphQLSchema.Builder#build()}
76+
* </li>
77+
*
78+
* <li>{@link graphql.GraphQLException} - is thrown as a general purpose runtime exception, for example if the code cant
79+
* access a named field when examining a POJO.
80+
* </li>
81+
*
82+
* <li>{@link graphql.AssertException} - is thrown as a low level code assertion exception for truly unexpected code conditions
83+
* </li>
84+
*
85+
* </ul>
4586
*/
4687
@PublicApi
4788
public class GraphQL {

‎src/main/java/graphql/ShouldNotHappenException.java‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎src/main/java/graphql/execution/ExecutionStrategy.java‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
package graphql.execution;
22

3+
import graphql.Assert;
34
import graphql.ExecutionResult;
45
import graphql.ExecutionResultImpl;
5-
import graphql.GraphQLException;
66
import graphql.PublicSpi;
77
import graphql.SerializationError;
88
import graphql.TypeResolutionEnvironment;
@@ -434,7 +434,7 @@ protected GraphQLObjectType resolveTypeForInterface(TypeResolutionParameters par
434434
TypeResolutionEnvironment env = new TypeResolutionEnvironment(params.getValue(), params.getArgumentValue 8E6E s(), params.getField(), params.getGraphQLInterfaceType(), params.getSchema());
435435
GraphQLObjectType result = params.getGraphQLInterfaceType().getTypeResolver().getType(env);
436436
if (result == null) {
437-
throw new GraphQLException("Could not determine the exact type of " + params.getGraphQLInterfaceType().getName());
437+
throw new UnresolvedTypeException(params.getGraphQLInterfaceType());
438438
}
439439
return result;
440440
}
@@ -450,7 +450,7 @@ protected GraphQLObjectType resolveTypeForUnion(TypeResolutionParameters params)
450450
TypeResolutionEnvironment env = new TypeResolutionEnvironment(params.getValue(), params.getArgumentValues(), params.getField(), params.getGraphQLUnionType(), params.getSchema());
451451
GraphQLObjectType result = params.getGraphQLUnionType().getTypeResolver().getType(env);
452452
if (result == null) {
453-
throw new GraphQLException("Could not determine the exact type of " + params.getGraphQLUnionType().getName());
453+
throw new UnresolvedTypeException(params.getGraphQLUnionType());
454454
}
455455
return result;
456456
}
@@ -602,9 +602,7 @@ protected GraphQLFieldDefinition getFieldDef(GraphQLSchema schema, GraphQLObject
602602
}
603603

604604
GraphQLFieldDefinition fieldDefinition = schema.getFieldVisibility().getFieldDefinition(parentType, field.getName());
605-
if (fieldDefinition == null) {
606-
throw new GraphQLException("Unknown field " + field.getName());
607-
}
605+
Assert.assertTrue(fieldDefinition != null, "Unknown field " + field.getName());
608606
return fieldDefinition;
609607
}
610608

‎src/main/java/graphql/execution/InputMapDefinesTooManyFieldsException.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package graphql.execution;
22

33
import graphql.GraphQLException;
4+
import graphql.PublicApi;
45
import graphql.schema.GraphQLType;
56
import graphql.schema.GraphQLTypeUtil;
67

@@ -9,6 +10,7 @@
910
*
1011
* - This unordered map should not contain any entries with names not defined by a field of this input object type, otherwise an error should be thrown.
1112
*/
13+
@PublicApi
1214
public class InputMapDefinesTooManyFieldsException extends GraphQLException {
1315

1416
public InputMapDefinesTooManyFieldsException(GraphQLType graphQLType, String fieldName) {

0 commit comments

Comments
 (0)
0