Better documentation

Author: bbakerman

readme.md

@@ -17,6 +17,7 @@ It has NOT yet been consumed by a production like project and hence its API usef
 
 TODO
 
+
 # SDL @Directive constraints
 
 This library a series of directives that can be applied to field arguments and input type fields which will constrain their allowable values.
@@ -49,8 +50,81 @@ For example
 In the example above, we have a `applications` argument that takes at most 10 applications and within each `Application` input object,
 the `name` field must be at least 3 characters long and no more than 100 characters long to be considered valid. 
 
+# Java Expression Language (Java EL)
+
+The `@Expression` validation directive allows Java EL to be used to help build validation rules.
+
+Java EL is a powerful expression syntax for expressing validation conditions.
+
+Some simple sample Java EL expressions might be : 
+
+| EL Expression                          | Result   |
+| -------------                          | -------- |
+| `${1> (4/2)} `                         | `false`  |
+| `${4.0>= 3} `                          | `true`   |
+| `${100.0 == 100}`                      | `true`   |
+| `${(10*10) ne 100} `                   | `false`  |
+| `${'a' > 'b'}`                         | `false`  |
+| `${'hip' lt 'hit'}`                    | `true`   |
+| `${4> 3} `                             | `true`   |
+| `${1.2E4 + 1.4}  `                     | `12001.4` |
+| `${3 div 4}`                           | `0.75`   |
+| `${10 mod 4}`                          | `2`      |
+| `${((x, y) → x + y)(3, 5.5)}`          | `8.5`    |
+| `[1,2,3,4].stream().sum()`             | `10`     |
+| `[1,3,5,2].stream().sorted().toList()` | `[1, 2, 3, 5]` |
+
+The following validation variables are made available to you : 
+
+| Name                  | Value |
+| -------------         | ----- |
+| `validatedValue`      | The value being validated |
+| `gqlField`            | The `GraphQLFieldDefinition` being validated |
+| `gqlFieldContainer`   | The `GraphQLFieldsContainer` parent type containing that field |
+| `gqlArgument`         | The `GraphQLArgument` being validated.  This can be null for field level validation |
+| `arguments`           | The map of all argument values for the current field |
+| `args`                | A short hand name for the map of all argument values for the current field | 
+
+The Java EL expression MUST evaluate to a boolean value to be useful in the `@Expresion` directive.
+
+See here for [a more complete overview of Java EL](https://javaee.github.io/tutorial/jsf-el001.html)
+
+
+# Message Interpolation
+
+The validation code uses a `graphql.validation.interpolation.MessageInterpolator` interface to build out error messages.  A default 
+`ResourceBundleMessageInterpolator` class is provided to load error messages from Java resource bundles to allow internationalised messages (I18N)
+
+You can use Java EL syntax in the message templates to format even more powerful error messages.
+
+```
+   The field ${gqlField.name} has the following invalid value : ${formatter.format('%1$.2f', validatedValue)}
+```
+
+If you use directive arguments like `message : String = "graphql.validation.Size.message"` then the `ResourceBundleMessageInterpolator` class
+will use that as a resource bundle lookup key.  This too is inspired by the javax.validation annotations and how they work.
+
+Like javax.validation, this library ships with some default error message templates but you can override them. 
+
+
+# Complex input types
+
+You can put @Directive constraints on complex input types as well as simple field arguments
+
+```graphql
+    input ProductItem {
+        code : String @Size(max : 5)
+        price : String @Size(max : 3)
+    }
+
+    type Mutation {
+            updateProduct( product : ID,  items : [ProductItem]) : Product
+    }   
+```
+
+In the example above each `ProductItem` in the list of items is examined for valid values
 
-## The supplied constraints
+## The supplied @Directive constraints
 
 <!-- generated by DocHelper on 2019-08-17T11:55:22.933Z -->
 

src/main/java/graphql/validation/constraints/AbstractDirectiveConstraint.java

@@ -26,6 +26,7 @@
 
 import static graphql.schema.GraphQLTypeUtil.isList;
 import static graphql.validation.rules.ValidationEnvironment.ValidatedElement.FIELD;
+import static graphql.validation.util.Util.mkMap;
 import static java.util.Collections.singletonList;
 
 @SuppressWarnings("UnnecessaryLocalVariable")
@@ -73,7 +74,7 @@ public boolean appliesTo(GraphQLArgument argument, GraphQLFieldDefinition fieldD
                 // if they have a @Directive on there BUT it cant handle that type
                 // then is a really bad situation
                 String argType = GraphQLTypeUtil.simplePrint(inputType);
-                Assert.assertShouldNeverHappen("The directive rule '%s' cannot be placed on elements of type '%s'", this.getName(), argType);
+                Assert.assertTrue(false, "The directive rule '%s' cannot be placed on elements of type '%s'", "@" + this.getName(), argType);
             }
             return false;
         });
@@ -282,24 +283,6 @@ protected Map<String, Object> mkMessageParams(Object validatedValue, ValidationE
     }
 
 
-    /**
-     * Makes a map of the args
-     *
-     * @param args must be an key / value array with String keys as the even params and values as then odd params
-     *
-     * @return a map of the args
-     */
-    protected Map<String, Object> mkMap(Object... args) {
-        Map<String, Object> params = new LinkedHashMap<>();
-        Assert.assertTrue(args.length % 2 == 0, "You MUST pass in an even number of arguments");
-        for (int ix = 0; ix < args.length; ix = ix + 2) {
-            Object key = args[ix];
-            Assert.assertTrue(key instanceof String, "You MUST pass in a message param string key");
-            Object val = args[ix + 1];
-            params.put(String.valueOf(key), val);
-        }
-        return params;
-    }
 
     /**
      * Creates  a new {@link graphql.GraphQLError}

src/main/java/graphql/validation/constraints/standard/ExpressionConstraint.java

@@ -8,12 +8,12 @@
 import graphql.validation.constraints.AbstractDirectiveConstraint;
 import graphql.validation.constraints.Documentation;
 import graphql.validation.el.ELSupport;
+import graphql.validation.el.StandardELVariables;
 import graphql.validation.rules.ValidationEnvironment;
 
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
-import java.util.function.Supplier;
 
 public class ExpressionConstraint extends AbstractDirectiveConstraint {
 
@@ -54,25 +54,13 @@ public boolean appliesTo(GraphQLFieldDefinition fieldDefinition, GraphQLFieldsCo
 
     @Override
     protected List<GraphQLError> runConstraint(ValidationEnvironment validationEnvironment) {
-        GraphQLFieldDefinition fieldDefinition = validationEnvironment.getFieldDefinition();
         GraphQLDirective directive = validationEnvironment.getContextObject(GraphQLDirective.class);
         String expression = helpWithCurlyBraces(getStrArg(directive, "value"));
 
-        Object argument = validationEnvironment.getArgument();
-        GraphQLFieldsContainer fieldsContainer = validationEnvironment.getFieldsContainer();
         Object validatedValue = validationEnvironment.getValidatedValue();
-        Map<String, Object> argumentValues = validationEnvironment.getArgumentValues();
 
-        Map<String, Object> variables = mkMap(
-                "validatedValue", validatedValue,
+        Map<String, Object> variables = StandardELVariables.standardELVars(validationEnvironment);
 
-                "gqlField", fieldDefinition,
-                "gqlFieldContainer", fieldsContainer,
-                "gqlArgument", argument,
-
-                "args", argumentValues, // short hand
-                "arguments", argumentValues
-        );
         ELSupport elSupport = new ELSupport(validationEnvironment.getLocale());
         boolean isOK = elSupport.evaluateBoolean(expression, variables);
 

src/main/java/graphql/validation/el/StandardELVariables.java

@@ -0,0 +1,32 @@
+package graphql.validation.el;
+
+import graphql.schema.GraphQLFieldDefinition;
+import graphql.schema.GraphQLFieldsContainer;
+import graphql.validation.rules.ValidationEnvironment;
+
+import java.util.Map;
+
+import static graphql.validation.util.Util.mkMap;
+
+public class StandardELVariables {
+
+    public static Map<String, Object> standardELVars(ValidationEnvironment validationEnvironment) {
+        GraphQLFieldDefinition fieldDefinition = validationEnvironment.getFieldDefinition();
+        Object argument = validationEnvironment.getArgument();
+        GraphQLFieldsContainer fieldsContainer = validationEnvironment.getFieldsContainer();
+        Object validatedValue = validationEnvironment.getValidatedValue();
+        Map<String, Object> argumentValues = validationEnvironment.getArgumentValues();
+
+        return mkMap(
+                "validatedValue", validatedValue,
+
+                "gqlField", fieldDefinition,
+                "gqlFieldContainer", fieldsContainer,
+
+                "gqlArgument", argument,
+
+                "args", argumentValues, // short hand
+                "arguments", argumentValues
+        );
+    }
+}

src/main/java/graphql/validation/interpolation/MessageInterpolator.java

@@ -8,7 +8,10 @@
 
 /**
  * This is responsible for taking an message template and parameters
- * and turning it into a {@link graphql.GraphQLError}
+ * and turning it into a {@link graphql.GraphQLError}.
+ * <p>
+ * Remember error messages are allow to use Java EL expressions, like <pre>{@code ${formatter.format('%1$.2f', validatedValue)}}</pre> to build
+ * more powerful error messages.
  */
 @PublicSpi
 public interface MessageInterpolator {
@@ -18,7 +21,6 @@ public interface MessageInterpolator {
      * @param messageTemplate       the message template
      * @param messageParams         the parameters to this error
      * @param validationEnvironment the validation environment
-     *
      * @return a {@link graphql.GraphQLError}
      */
     GraphQLError interpolate(String messageTemplate, Map<String, Object> messageParams, ValidationEnvironment validationEnvironment);

src/main/java/graphql/validation/interpolation/ResourceBundleMessageInterpolator.java

@@ -5,6 +5,7 @@
 import graphql.GraphqlErrorBuilder;
 import graphql.execution.ExecutionPath;
 import graphql.schema.GraphQLDirective;
+import graphql.validation.el.StandardELVariables;
 import graphql.validation.rules.ValidationEnvironment;
 import org.hibernate.validator.internal.engine.MessageInterpolatorContext;
 import org.hibernate.validator.internal.metadata.core.ConstraintHelper;
@@ -152,8 +153,7 @@ private MessageInterpolatorContext buildHibernateContext(Map<String, Object> mes
                 annotationDescriptor, ElementType.FIELD
         );
 
-        // TODO - we should we put in here extra??
-        Map<String, Object> expressionVariables = Collections.emptyMap();
+        Map<String, Object> expressionVariables = StandardELVariables.standardELVars(validationEnvironment);
 
         Class<?> rootBeanType = null;
         return new MessageInterpolatorContext(

src/main/java/graphql/validation/rules/OnValidationErrorStrategy.java

@@ -8,8 +8,10 @@
 import java.util.List;
 
 /**
- * A callback that indicates whether to continue after errors and if not what value should be
- * returned.
+ * A callback that indicates whether to continue the data fetching after validation errors are detected  and what value should be
+ * returned if it decides to not continue.
+ * <p>
+ * {@link #RETURN_NULL} is a common strategy to use, that is return null as the value for an invalid field
  */
 @PublicSpi
 public interface OnValidationErrorStrategy {
@@ -35,7 +37,6 @@ public Object onErrorValue(List<GraphQLError> errors, DataFetchingEnvironment en
      *
      * @param errors      the list errors
      * @param environment the environment in play
-     *
      * @return true if the current data fetch should continue
      */
     boolean shouldContinue(List<GraphQLError> errors, DataFetchingEnvironment environment);
@@ -45,7 +46,6 @@ public Object onErrorValue(List<GraphQLError> errors, DataFetchingEnvironment en
      *
      * @param errors      the list errors
      * @param environment the environment in play
-     *
      * @return an object (a sensible value would be null)
      */
     Object onErrorValue(List<GraphQLError> errors, DataFetchingEnvironment environment);

src/main/java/graphql/validation/rules/PossibleValidationRules.java

@@ -123,6 +123,14 @@ public Builder messageInterpolator(MessageInterpolator messageInterpolator) {
             return this;
         }
 
+        /**
+         * This sets the locale of the possible rules.  This is only needed while graphql-java does not allow you to get the
+         * locale from the {@link graphql.ExecutionInput}.  A PR for this is in the works.  Once that is available, then this method
+         * will not be as useful.
+         *
+         * @param locale the locale to use for message interpolation
+         * @return this builder
+         */
         public Builder locale(Locale locale) {
             this.locale = locale;
             return this;

src/main/java/graphql/validation/rules/ValidationCoordinates.java

@@ -8,6 +8,9 @@
 import java.util.Objects;
 import java.util.StringJoiner;
 
+/**
+ * Validation rules can be co-ordinated on a field (within a fields container) or an argument on a field (within a fields container)
+ */
 @PublicApi
 public class ValidationCoordinates {
 

src/main/java/graphql/validation/rules/ValidationRules.java

@@ -32,7 +32,9 @@
 
 /**
  * ValidationRules is a holder of {@link graphql.validation.rules.ValidationRule}s against a specific
- * type, field and possible argument via {@link ValidationCoordinates}
+ * type, field and possible argument via {@link ValidationCoordinates}.  It then allows those rules
+ * to be run against the specific fields based on runtime execution during {@link graphql.schema.DataFetcher}
+ * invocations.
  */
 @PublicApi
 public class ValidationRules {
@@ -51,6 +53,14 @@ public boolean isEmpty() {
         return rulesMap.isEmpty();
     }
 
+    /**
+     * Runs the contained rules that match the currently executing field named by the {@link graphql.schema.DataFetchingEnvironment}
+     *
+     * @param env          the field being executed
+     * @param interpolator the message interpolator to use
+     * @param locale       the locale in play
+     * @return a list of zero or more data validation errors
+     */
     public List<GraphQLError> runValidationRules(DataFetchingEnvironment env, MessageInterpolator interpolator, Locale locale) {
 
         List<GraphQLError> errors = new ArrayList<>();