Moar tests an some documentation

Author: bbakerman

TODO.md

@@ -0,0 +1,12 @@
+
+
+# add the ability to do inter argument validation
+
+eg imagine
+
+    field( first : Int, after : ID, last : Int, before : ID)
+    
+can we do a validation rule where we require `first`+`after` or `last` + `before` but not all 4 together??
+
+Currently the rules are single argument specific - we would need field specific rules
+

build.gradle

@@ -41,8 +41,9 @@ dependencies {
     compile "com.graphql-java:graphql-java:12.0"
     compile "javax.validation:validation-api:2.0.1.Final"
     compile "org.hibernate.validator:hibernate-validator:6.0.10.Final"
-
-    testCompile 'org.spockframework:spock-core:1.1-groovy-2.4'
+    compile "javax.el:javax.el-api:3.0.0"
+    compile "org.glassfish.web:javax.el:2.2.6"
+            testCompile 'org.spockframework:spock-core:1.1-groovy-2.4'
     testCompile 'org.codehaus.groovy:groovy-all:2.5.7'
 }
 

readme.md

@@ -2,3 +2,155 @@
 
 This library provides extended validation for [graphql-java](https://github.com/graphql-java/graphql-java)
 
+
+# Status
+
+This code is current under construction.  There is no release and not all parts of it are ready.
+
+But the project welcomes all feedback and input on code design and validation requirements. 
+
+# Using the code
+
+TODO
+
+# SDL @Directive validation
+
+This library a series of directives that can be applied to field arguments and input type fields which will constrain the values
+
+These names and semantics are inspired from the javax.validation annotations
+
+https://javaee.github.io/javaee-spec/javadocs/javax/validation/constraints/package-summary.html
+
+## SDL directives
+
+You can add these onto arguments or input types in your graphql SDL.
+
+For example
+
+```graphql
+
+    #
+    # this declares the directive as being possible on arguments and input fields
+    #
+    directive @Size(min : Int = 0, max : Int = 2147483647, message : String = "graphql.validation.Size.message")
+                        on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+
+    input Application {
+        name : String @Size(min : 3, max : 100)
+    }
+
+    type Query {
+        hired (applications : [Application!] @Size(max : 10)) : [Boolean]
+    }
+```
+
+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. 
+
+
+## The library supplied directives
+
+### AssertFalse
+
+The boolean value must be false.
+
+- SDL :  `directive @AssertFalse(message : String = "graphql.validation.AssertFalse.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Boolean`
+
+### AssertTrue
+
+The boolean value must be true.
+
+- SDL :  `directive @AssertTrue(message : String = "graphql.validation.AssertTrue.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Boolean`
+
+### DecimalMax
+
+The element must be a number whose value must be less than or equal to the specified maximum.
+
+- SDL :  `directive @DecimalMax(value : String!, inclusive : Boolean! = true, message : String = "graphql.validation.DecimalMax.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### DecimalMin
+
+The element must be a number whose value must be greater than or equal to the specified minimum.
+
+- SDL :  `directive @DecimalMin(value : String!, inclusive : Boolean! = true, message : String = "graphql.validation.DecimalMin.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### Digits
+
+The element must be a number inside the specified `integer` and `fraction` range.
+
+- SDL :  `directive @Digits(integer : Int!, fraction : Int!, message : String = "graphql.validation.Digits.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`, `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### Max
+
+The element must be a number whose value must be less than or equal to the specified maximum.
+
+- SDL :  `directive @Max(value : Int! = 2147483647, message : String = "graphql.validation.Max.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### Min
+
+The element must be a number whose value must be greater than or equal to the specified minimum.
+
+- SDL :  `directive @Min(value : Int! = 0, message : String = "graphql.validation.Min.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### Negative
+
+The element must be a negative number.
+
+- SDL :  `directive @Negative(message : String = "graphql.validation.Negative.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### NegativeOrZero
+
+The element must be a negative number or zero.
+
+- SDL :  `directive @NegativeOrZero(message : String = "graphql.validation.NegativeOrZero.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### NotBlank
+
+The String must contain at least one non-whitespace character, according to Java's Character.isWhitespace().
+
+- SDL :  `directive @NotBlank(message : String = "graphql.validation.NotBlank.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`
+
+### NotEmpty
+
+The element must have a non zero size.
+
+- SDL :  `directive @NotEmpty(message : String = "graphql.validation.NotEmpty.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`, `Lists`, `Input Objects`
+
+### Pattern
+
+The String must match the specified regular expression, which follows the Java regular expression conventions.
+
+- SDL :  `directive @Pattern(pattern : String! =".*", message : String = "graphql.validation.Pattern.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`
+
+### Positive
+
+The element must be a positive number.
+
+- SDL :  `directive @Positive(message : String = "graphql.validation.Positive.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### PositiveOrZero
+
+The element must be a positive number or zero.
+
+- SDL :  `directive @PositiveOrZero(message : String = "graphql.validation.PositiveOrZero.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `Byte`, `Short`, `Int`, `Long`, `BigDecimal`, `BigInteger`, `Float`
+
+### Size
+
+The element size must be between the specified `min` and `max` boundaries (inclusive).
+
+- SDL :  `directive @Size(min : Int = 0, max : Int = 2147483647, message : String = "graphql.validation.Size.message") on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION`
+- Applies to :  `String`, `Lists`, `Input Objects`

src/main/java/graphql/validation/ExtendedValidation.java

@@ -1,4 +1,7 @@
 package graphql.validation;
 
+import graphql.PublicApi;
+
+@PublicApi
 public class ExtendedValidation {
 }

src/main/java/graphql/validation/directives/AbstractDirectiveValidationRule.java

@@ -2,6 +2,7 @@
 
 import graphql.Assert;
 import graphql.GraphQLError;
+import graphql.PublicSpi;
 import graphql.Scalars;
 import graphql.schema.GraphQLArgument;
 import graphql.schema.GraphQLDirective;
@@ -23,6 +24,7 @@
 import static graphql.schema.GraphQLTypeUtil.isList;
 import static java.util.Collections.singletonList;
 
+@PublicSpi
 public abstract class AbstractDirectiveValidationRule implements DirectiveValidationRule {
 
     private final String name;
@@ -41,6 +43,14 @@ public boolean appliesToType(GraphQLArgument argument, GraphQLFieldDefinition fi
         return appliesToType(Util.unwrapNonNull(argument.getType()));
     }
 
+    /**
+     * Returns true of the input type is one of the specified scalar types, regardless of non null ness
+     *
+     * @param inputType   the type to check
+     * @param scalarTypes the array of scalar types
+     *
+     * @return true ifits oneof them
+     */
     protected boolean isOneOfTheseTypes(GraphQLInputType inputType, GraphQLScalarType... scalarTypes) {
         GraphQLInputType unwrappedType = Util.unwrapNonNull(inputType);
         for (GraphQLScalarType scalarType : scalarTypes) {
@@ -51,6 +61,14 @@ protected boolean isOneOfTheseTypes(GraphQLInputType inputType, GraphQLScalarTyp
         return false;
     }
 
+    /**
+     * Returns an integer argument from a directive (or its default) and throws an assertion of the argument is null
+     *
+     * @param directive the directive to check
+     * @param argName   the argument name
+     *
+     * @return a non null value
+     */
     protected int getIntArg(GraphQLDirective directive, String argName) {
         GraphQLArgument argument = directive.getArgument(argName);
         if (argument == null) {
@@ -66,6 +84,14 @@ protected int getIntArg(GraphQLDirective directive, String argName) {
         return value.intValue();
     }
 
+    /**
+     * Returns an String argument from a directive (or its default) and throws an assertion of the argument is null
+     *
+     * @param directive the directive to check
+     * @param argName   the argument name
+     *
+     * @return a non null value
+     */
     protected String getStrArg(GraphQLDirective directive, String argName) {
         GraphQLArgument argument = directive.getArgument(argName);
         if (argument == null) {
@@ -81,6 +107,14 @@ protected String getStrArg(GraphQLDirective directive, String argName) {
         return value;
     }
 
+    /**
+     * Returns an boolean argument from a directive (or its default) and throws an assertion of the argument is null
+     *
+     * @param directive the directive to check
+     * @param argName   the argument name
+     *
+     * @return a non null value
+     */
     protected boolean getBoolArg(GraphQLDirective directive, String argName) {
         GraphQLArgument argument = directive.getArgument(argName);
         if (argument == null) {
@@ -96,6 +130,14 @@ protected boolean getBoolArg(GraphQLDirective directive, String argName) {
         return Boolean.parseBoolean(String.valueOf(value));
     }
 
+    /**
+     * Returns the "message : String" argument from a directive or makes up one
+     * called "graphql.validation.{name}.message"
+     *
+     * @param directive the directive to check
+     *
+     * @return a non null value
+     */
     protected String getMessageTemplate(GraphQLDirective directive) {
         String msg = null;
         GraphQLArgument arg = directive.getArgument("message");
@@ -111,6 +153,13 @@ protected String getMessageTemplate(GraphQLDirective directive) {
         return msg;
     }
 
+    /**
+     * Creates a map of named parameters for message interpolation
+     *
+     * @param args must be even with a String as even params and values as odd params
+     *
+     * @return a map of message parameters
+     */
     protected Map<String, Object> mkMessageParams(Object... args) {
         Assert.assertTrue(args.length % 2 == 0, "You MUST pass in an even number of arguments");
         Map<String, Object> params = new LinkedHashMap<>();
@@ -124,25 +173,51 @@ protected Map<String, Object> mkMessageParams(Object... args) {
         return params;
     }
 
+    /**
+     * Creates  a new {@link graphql.GraphQLError}
+     *
+     * @param ruleEnvironment the current rules environment
+     * @param directive       the directive being run
+     * @param msgParams       the map of parameters
+     *
+     * @return a list of a single error
+     */
     protected List<GraphQLError> mkError(ValidationRuleEnvironment ruleEnvironment, GraphQLDirective directive, Map<String, Object> msgParams) {
         String messageTemplate = getMessageTemplate(directive);
         GraphQLError error = ruleEnvironment.getInterpolator().interpolate(messageTemplate, msgParams, ruleEnvironment);
         return singletonList(error);
     }
 
-    protected boolean isStringOrListOrMap(GraphQLInputType argumentType) {
-        GraphQLInputType unwrappedType = Util.unwrapOneAndAllNonNull(argumentType);
+    /**
+     * Return true if the type is a String or List type or {@link graphql.schema.GraphQLInputObjectType}, regardless of non null ness
+     *
+     * @param inputType the type to check
+     *
+     * @return true if one of the above
+     */
+    protected boolean isStringOrListOrMap(GraphQLInputType inputType) {
+        GraphQLInputType unwrappedType = Util.unwrapOneAndAllNonNull(inputType);
         return Scalars.GraphQLString.equals(unwrappedType) ||
-                isList(argumentType) ||
+                isList(inputType) ||
                 (unwrappedType instanceof GraphQLInputObjectType);
     }
 
+    /**
+     * Casts the object as a Map with an assertion of it is not one
+     *
+     * @return a Map
+     */
     @SuppressWarnings("ConstantConditions")
     protected Map asMap(Object value) {
         Assert.assertTrue(value instanceof Map, "The argument value MUST be a Map value");
         return (Map) value;
     }
 
+    /**
+     * Makes the object a BigDecimal with an assertion if we have no conversion of it
+     *
+     * @return a BigDecimal
+     */
     protected BigDecimal asBigDecimal(Object value) throws NumberFormatException {
         if (value == null) {
             return Assert.assertShouldNeverHappen("Validation cant handle null objects BigDecimals");
@@ -161,6 +236,11 @@ protected BigDecimal asBigDecimal(Object value) throws NumberFormatException {
         return new BigDecimal(bdStr);
     }
 
+    /**
+     * Makes the object a boolean with an assertion if we have no conversion of it
+     *
+     * @return a boolean
+     */
     protected boolean asBoolean(Object value) {
         if (value == null) {
             return Assert.assertShouldNeverHappen("Validation cant handle null objects Booleans");
@@ -172,16 +252,24 @@ protected boolean asBoolean(Object value) {
         }
     }
 
-    protected int getStringOrObjectOrMapLength(GraphQLInputType inputType, Object argumentValue) {
+    /**
+     * Returns the length of a String of the size of a list or size of a Map
+     *
+     * @param inputType the input type
+     * @param value     the value
+     *
+     * @return the length of a String or Map or List
+     */
+    protected int getStringOrObjectOrMapLength(GraphQLInputType inputType, Object value) {
         int valLen;
-        if (argumentValue == null) {
+        if (value == null) {
             valLen = 0;
         } else if (Scalars.GraphQLString.equals(Util.unwrapNonNull(inputType))) {
-            valLen = String.valueOf(argumentValue).length();
+            valLen = String.valueOf(value).length();
         } else if (isList(inputType)) {
-            valLen = getListLength(argumentValue);
+            valLen = getListLength(value);
         } else {
-            valLen = getObjectLen(argumentValue);
+            valLen = getObjectLen(value);
         }
         return valLen;
     }