Added unary comparator support for isnull/notnull

Author: tricolor2

src/main/java/cz/jirutka/rsql/parser/RSQLParser.java

@@ -27,12 +27,12 @@
 import cz.jirutka.rsql.parser.ast.Node;
 import cz.jirutka.rsql.parser.ast.NodesFactory;
 import cz.jirutka.rsql.parser.ast.RSQLOperators;
-import net.jcip.annotations.Immutable;
-
+import cz.jirutka.rsql.parser.ast.UnaryComparisonOperator;
 import java.io.ByteArrayInputStream;
 import java.io.InputStream;
 import java.nio.charset.Charset;
 import java.util.Set;
+import net.jcip.annotations.Immutable;
 
 /**
  * Parser of the RSQL (RESTful Service Query Language).
@@ -43,30 +43,33 @@
  *
  * <p><b>Grammar in EBNF notation:</b>
  * <pre>{@code
- * input          = or, EOF;
- * or             = and, { ( "," | " or " ) , and };
- * and            = constraint, { ( ";" | " and " ), constraint };
- * constraint     = ( group | comparison );
- * group          = "(", or, ")";
+ * input           = or, EOF;
+ * or              = and, { ( "," | " or " ) , and };
+ * and             = constraint, { ( ";" | " and " ), constraint };
+ * constraint      = ( group | comparison );
+ * group           = "(", or, ")";
  *
- * comparison     = selector, comparator, arguments;
- * selector       = unreserved-str;
+ * comparison      = selector, comparator-node;
+ * comparator-node = (comparator , arguments) | (comp-cust, arguments-cust);
+ * selector        = unreserved-str;
  *
- * comparator     = comp-fiql | comp-alt;
- * comp-fiql      = ( ( "=", { ALPHA } ) | "!" ), "=";
- * comp-alt       = ( ">" | "<" ), [ "=" ];
+ * comparator      = comp-fiql | comp-alt;
+ * comp-fiql       = ("==", "!=");
+ * comp-alt        = ( ">" | "<" ), [ "=" ];
+ * comp-cust       = "=" ALPHA { ALPHA } "=";
  *
- * arguments      = ( "(", value, { "," , value }, ")" ) | value;
- * value          = unreserved-str | double-quoted | single-quoted;
+ * arguments       = ( "(", value, { "," , value }, ")" ) | value;
+ * arguments-cust  = ( "(", value, { "," , value }, ")" ) | [value];
+ * value           = unreserved-str | double-quoted | single-quoted;
  *
- * unreserved-str = unreserved, { unreserved }
- * single-quoted  = "'", { ( escaped | all-chars - ( "'" | "\" ) ) }, "'";
- * double-quoted  = '"', { ( escaped | all-chars - ( '"' | "\" ) ) }, '"';
+ * unreserved-str  = unreserved, { unreserved }
+ * single-quoted   = "'", { ( escaped | all-chars - ( "'" | "\" ) ) }, "'";
+ * double-quoted   = '"', { ( escaped | all-chars - ( '"' | "\" ) ) }, '"';
  *
- * reserved       = '"' | "'" | "(" | ")" | ";" | "," | "=" | "!" | "~" | "<" | ">" | " ";
- * unreserved     = all-chars - reserved;
- * escaped        = "\", all-chars;
- * all-chars      = ? all unicode characters ?;
+ * reserved        = '"' | "'" | "(" | ")" | ";" | "," | "=" | "!" | "~" | "<" | ">" | " ";
+ * unreserved      = all-chars - reserved;
+ * escaped         = "\", all-chars;
+ * all-chars       = ? all unicode characters ?;
  * }</pre>
  *
  * @version 2.1
@@ -80,23 +83,24 @@ public final class RSQLParser {
 
 
     /**
-     * Creates a new instance of {@code RSQLParser} with the default set of comparison operators.
+     * Creates a new instance of {@code RSQLParser} with the default set of comparison and unary operators.
      */
     public RSQLParser() {
-        this.nodesFactory = new NodesFactory(RSQLOperators.defaultOperators());
+        this.nodesFactory = new NodesFactory(RSQLOperators.defaultComparisonOperators(), RSQLOperators.defaultUnaryOperator());
     }
 
     /**
      * Creates a new instance of {@code RSQLParser} that supports only the specified comparison
      * operators.
      *
-     * @param operators A set of supported comparison operators. Must not be <tt>null</tt> or empty.
+     * @param comparisonOperators A set of supported comparison operators. Must not be <tt>null</tt> or empty.
+     * @param unaryComparisonOperators A set of supported unary operators. Must not be <tt>null</tt> or empty.
      */
-    public RSQLParser(Set<ComparisonOperator> operators) {
-        if (operators == null || operators.isEmpty()) {
+    public RSQLParser(Set<ComparisonOperator> comparisonOperators, Set<UnaryComparisonOperator> unaryComparisonOperators) {
+        if (comparisonOperators == null || comparisonOperators.isEmpty() || unaryComparisonOperators == null || unaryComparisonOperators.isEmpty()) {
             throw new IllegalArgumentException("operators must not be null or empty");
         }
-        this.nodesFactory = new NodesFactory(operators);
+        this.nodesFactory = new NodesFactory(comparisonOperators, unaryComparisonOperators);
     }
 
     /**

src/main/java/cz/jirutka/rsql/parser/ast/NoArgRSQLVisitorAdapter.java

@@ -37,6 +37,8 @@ public abstract class NoArgRSQLVisitorAdapter<R> implements RSQLVisitor<R, Void>
 
     public abstract R visit(ComparisonNode node);
 
+    public abstract R visit(UnaryComparisonNode node);
+
 
     public R visit(AndNode node, Void param) {
         return visit(node);
@@ -49,4 +51,6 @@ public R visit(OrNode node, Void param) {
     public R visit(ComparisonNode node, Void param) {
         return visit(node);
     }
+
+    public R visit(UnaryComparisonNode node, Void param){ return visit(node); }
 }

src/main/java/cz/jirutka/rsql/parser/ast/NodesFactory.java

@@ -38,14 +38,21 @@
 public class NodesFactory {
 
     private final Map<String, ComparisonOperator> comparisonOperators;
+    private final Map<String, UnaryComparisonOperator> unaryComparisonOperators;
 
+    public NodesFactory(Set<ComparisonOperator> comparisonOperators, Set<UnaryComparisonOperator> unaryOperators) {
 
-    public NodesFactory(Set<ComparisonOperator> operators) {
+        this.comparisonOperators = new HashMap<>(comparisonOperators.size());
+        for (ComparisonOperator op : comparisonOperators) {
+            for (String sym : op.getSymbols()) {
+                this.comparisonOperators.put(sym, op);
+            }
+        }
 
-        comparisonOperators = new HashMap<>(operators.size());
-        for (ComparisonOperator op : operators) {
+        this.unaryComparisonOperators = new HashMap<>(unaryOperators.size());
+        for (UnaryComparisonOperator op : unaryOperators) {
             for (String sym : op.getSymbols()) {
-                comparisonOperators.put(sym, op);
+                this.unaryComparisonOperators.put(sym, op);
             }
         }
     }
@@ -88,4 +95,24 @@ public ComparisonNode createComparisonNode(
             throw new UnknownOperatorException(operatorToken);
         }
     }
+
+    /**
+     * Creates a {@link UnaryComparisonNode} instance with the given parameters.
+     *
+     * @param operatorToken A textual representation of the comparison operator to be found in the
+     *                      set of supported {@linkplain UnaryComparisonOperator operators}.
+     * @param selector The selector that specifies the left side of the comparison.
+     *
+     * @throws UnknownOperatorException If no operator for the specified operator token exists.
+     */
+    public UnaryComparisonNode createUnaryComparisonNode(
+        String operatorToken, String selector) throws UnknownOperatorException {
+
+        UnaryComparisonOperator op = unaryComparisonOperators.get(operatorToken);
+        if (op != null) {
+            return new UnaryComparisonNode(op, selector);
+        } else {
+            throw new UnknownOperatorException(operatorToken);
+        }
+    }
 }

src/main/java/cz/jirutka/rsql/parser/ast/RSQLOperators.java

@@ -41,8 +41,16 @@ public abstract class RSQLOperators {
             NOT_IN = new ComparisonOperator("=out=", true);
 
 
-    public static Set<ComparisonOperator> defaultOperators() {
+    public static Set<ComparisonOperator> defaultComparisonOperators() {
         return new HashSet<>(asList(EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL,
                                     LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN));
     }
+
+    public static final UnaryComparisonOperator
+            IS_NULL = new UnaryComparisonOperator("=isnull="),
+            NOT_NULL = new UnaryComparisonOperator("=notnull=");
+
+    public static Set<UnaryComparisonOperator> defaultUnaryOperator(){
+        return new HashSet<>(asList(IS_NULL, NOT_NULL));
+    }
 }

src/main/java/cz/jirutka/rsql/parser/ast/RSQLVisitor.java

@@ -36,4 +36,6 @@ public interface RSQLVisitor<R, A> {
     R visit(OrNode node, A param);
 
     R visit(ComparisonNode node, A param);
+
+    R visit(UnaryComparisonNode node, A param);
 }

src/main/java/cz/jirutka/rsql/parser/ast/UnaryComparisonNode.java

@@ -0,0 +1,72 @@
+package cz.jirutka.rsql.parser.ast;
+
+import java.util.Objects;
+
+public class UnaryComparisonNode extends AbstractNode {
+
+    private final UnaryComparisonOperator operator;
+    private final String selector;
+
+    /**
+     * @param operator Must not be <tt>null</tt>.
+     * @param selector ust not be <tt>null</tt> or blank.
+     *
+     * @throws IllegalArgumentException If one of the conditions specified above it not met.
+     */
+    public UnaryComparisonNode(UnaryComparisonOperator operator, String selector){
+        Assert.notNull(operator, "operator must not be null");
+        Assert.notBlank(selector, "selector must not be blank");
+
+        this.operator = operator;
+        this.selector = selector;
+    }
+
+    public <R, A> R accept(RSQLVisitor<R, A> visitor, A param) {
+        return visitor.visit(this, param);
+    }
+
+    public UnaryComparisonOperator getOperator(){ return operator; }
+
+    /**
+     * Returns a copy of this node with the specified operator.
+     *
+     * @param newOperator Must not be <tt>null</tt>.
+     */
+    public UnaryComparisonNode withOperator(UnaryComparisonOperator newOperator) {
+        return new UnaryComparisonNode(newOperator, selector);
+    }
+
+    public String getSelector() {
+        return selector;
+    }
+
+    /**
+     * Returns a copy of this node with the specified selector.
+     *
+     * @param newSelector Must not be <tt>null</tt> or blank.
+     */
+    public UnaryComparisonNode withSelector(String newSelector) {
+        return new UnaryComparisonNode(operator, newSelector);
+    }
+
+    @Override
+    public String toString() {
+        return selector + operator;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        UnaryComparisonNode unaryNode = (UnaryComparisonNode) o;
+        return Objects.equals(operator, unaryNode.operator) &&
+            Objects.equals(selector, unaryNode.selector);
+    }
+
+    @Override
+    public int hashCode() {
+        int result = selector.hashCode();
+        result = 31 * result + operator.hashCode();
+        return result;
+    }
+}

src/main/java/cz/jirutka/rsql/parser/ast/UnaryComparisonOperator.java

@@ -0,0 +1,85 @@
+package cz.jirutka.rsql.parser.ast;
+
+import static cz.jirutka.rsql.parser.ast.StringUtils.isBlank;
+
+import java.util.regex.Pattern;
+import jdk.nashorn.internal.ir.annotations.Immutable;
+
+@Immutable
+public final class UnaryComparisonOperator {
+
+    private static final Pattern SYMBOL_PATTERN = Pattern.compile("=[a-zA-Z]+=");
+
+    private final String[] symbols;
+
+    /**
+     * @param symbols Textual representation of this operator (e.g. <tt><null></></tt>); the first item
+     *          is primary representation, any others are alternatives. Must match
+     *          <tt><[a-zA-Z]+></tt>.
+     *
+     * @throws IllegalArgumentException If the {@code symbols} is either <tt>null</tt>, empty,
+     *          or contain illegal symbols.
+     */
+    public UnaryComparisonOperator(String symbols[]){
+        Assert.notEmpty(symbols, "symbols must not be null or empty");
+        for (String sym : symbols) {
+            Assert.isTrue(isValidOperatorSymbol(sym), "symbol must match: %s", SYMBOL_PATTERN);
+        }
+        this.symbols = symbols.clone();
+    }
+
+    /**
+     * @see #UnaryComparisonOperator(String[])
+     */
+    public UnaryComparisonOperator(String symbol) {
+        this(new String[]{symbol});
+    }
+
+    /**
+     * @see #UnaryComparisonOperator(String[])
+     */
+    public UnaryComparisonOperator(String symbol, String altSymbol) {
+        this(new String[]{symbol, altSymbol});
+    }
+
+    /**
+     * Returns the primary representation of this operator.
+     */
+    public String getSymbol() {
+        return symbols[0];
+    }
+
+    /**
+     * Returns all representations of this operator. The first item is always the primary
+     * representation.
+     */
+    public String[] getSymbols() {
+        return symbols.clone();
+    }
+
+    /**
+     * Whether the given string can represent an operator.
+     * Note: Allowed symbols are limited by the RSQL syntax (i.e. parser).
+     */
+    private boolean isValidOperatorSymbol(String str) {
+        return !isBlank(str) && SYMBOL_PATTERN.matcher(str).matches();
+    }
+
+    @Override
+    public String toString() {
+        return getSymbol();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        UnaryComparisonOperator that = (UnaryComparisonOperator) o;
+        return getSymbol().equals(that.getSymbol());
+    }
+
+    @Override
+    public int hashCode() {
+        return getSymbol().hashCode();
+    }
+}