# Contains.java

    /*
    ** Module   : Contains.java
    ** Abstract : simplified implementation of the CONTAINS operator for lightweight use
    **
    ** Copyright (c) 2018-2025, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --------------------------------Description----------------------------------
    ** 001 ECF 20180830 Created initial version.
    ** 002 ECF 20190309 Silently tolerate, but do not match on an empty string expression.
    ** 003 CA  20190821 Allow a specified set of characters to be used as word delimiters.
    ** 004 IAS 20201113 Re-worked using Reverse Polish Notation and LogicalExpressionConverter
    ** 005 GBB 20230512 Logging methods replaced by CentralLogger/ConversionStatus.
    ** 006 SP  20240612 Improved word split logic using regex Pattern.split().
    ** 007 SP  20241111 Avoid duplicate call to word.toUpperCase(). Javadoc fixes.
    ** 008 SP  20250311 Performance improvements for words() method.
    */

    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.persist.pl;

    import java.util.*;
    import java.util.regex.*;
    import java.util.concurrent.*;

    import com.goldencode.p2j.util.*;
    import com.goldencode.p2j.util.LogicalExpressionConverter.*;
    import com.goldencode.p2j.util.logging.*;

    /**
     * Simplified implementation of the CONTAINS operator for lightweight use. Evaluates a data
     * string against an expression which uses the CONTAINS operator's right operand expression
     * syntax:
     * <pre>
     * Construct   Precedence   Description
     * -----------------------------------------------------------------------------------------------
     * (...)          3         Parentheses to change precedence of a subexpression operation.
     * word           3         A full word to match
     * prefix         3         A prefix of a word to match, followed by an asterisk (*), indicating
     *                          a wildcard. The asterisk may only be at the end of the word.
     * &amp;              2         Logical AND operator.
     * | or ! or ^    1         Logical OR operator.
     * </pre>
     * <p>
     * Subexpressions may be nested arbitrarily deeply. An empty expression is silently tolerated,
     * but does not produce a match.
     * <p>
     * Match tests are performed by constructing an instance of this class and invoking the
     * {@link #evaluate(String)} method against it. The match expression is parsed into an AST, and
     * the AST is walked to evaluate the expression for the data passed to the {@code evaluate}
     * method.
     * <p>
     * In practice, a separate instance of this class is constructed for every data match. This
     * design is necessary because this class will be used from within a database user defined
     * function, which is driven statelessly by a database in connection with a query. Thus, we have
     * no control over when or how often the feature is used. To amortize the expense of parsing the
     * match expression, a cache is used to permit re-use of previously parsed expression ASTs.
     * Since ASTs may be shared across threads, they are treated as immutable.
     * <p>
     * NOTE: since this implementation does not leverage true word break tables and joins, it is not
     * suitable for use with large tables nor tables with very large data entries. Since it is used
     * with a UDF that will be opaque to a database's query planner, this implementation often will
     * result in full table scans, unless other components of a query allow the query planner to
     * make a more efficient plan. In addition, each data entry will be scanned for each invocation.
     * Thus, this implementation is suitable for lightweight uses where the primary objective is to
     * properly honor the syntax of the CONTAINS operator's match expression.
     * <p>
     * TODO: properly handle match expression characters Progress simply ignores when matching. Do
     * these have to do with word break rules?
     * <p>
     * TODO: at this time, word break rules are not used to delimit words.
     *
     * @author  ecf
     */
    public final class Contains
    {
       /** Logger. */
       private static final CentralLogger LOG = CentralLogger.get(Contains.class);

       /** Cache of match expressions to parsed ASTs. */
       private static final Map<String, List<EToken>> cache = new ConcurrentHashMap<>();

       /** Cache for a set of characters considered as delimiters. */
       private static final BitSet DELIMITERS = new BitSet(128);

       /** Cache for a set of characters not considered as delimiters. */
       private static final BitSet NOT_DELIMITERS = new BitSet(128);

       /** Regular expression pattern used to identify delimiters for splitting words. */
       private final Pattern delimiterPattern;

       /** Should matches be checked case-sensitively? */
       private final boolean caseSensitive;

       /** Parsed match expression RPN, used to evaluate matches with string data */
       private final List<EToken> exprRPN;

       /**
        * Constructor.
        *
        * @param   expr
        *          Match expression which uses CONTAINS operator syntax.
        * @param   codePage
        *          Character encoding used.
        *
        * @throws  ErrorConditionException
        *          if there is an I/O error parsing the match expression.
        */
       public Contains(String expr, String codePage)
       {
          this(expr, false, codePage);
       }

       /**
        * Constructor.
        *
        * @param   expr
        *          Match expression which uses CONTAINS operator syntax.
        * @param   caseSensitive
        *          {@code true} to perform word match comparisons case-sensitively, {@code false} to
        *          ignore case.
        * @param   codePage
        *          Character encoding used.
        *
        * @throws  ErrorConditionException
        *          if there is a syntax or an I/O error parsing the match expression.
        */
       public Contains(String expr, boolean caseSensitive, String codePage)
       {
          this.delimiterPattern = I18nOps.getDelimiterPattern(codePage);
          this.caseSensitive = caseSensitive;
          this.exprRPN = expr == null ? Collections.emptyList() : cache.computeIfAbsent(
                expr,
                exp -> new LogicalExpressionConverter(exp, caseSensitive, codePage).toRPN(false)
          );
       }

       /**
        * Given a data string, evaluate the expression to determine whether the data matches. Only
        * read as many words from the data as are needed to determine a result.
        *
        * @param   data
        *          A data string with words delimited by this object's specified delimiter.
        *
        * @return  {@code true} if the words in the data match this object's expression, else
        *          {@code false}.
        *
        * @throws  ErrorConditionException
        *          if there is an I/O error reading words from the data stream.
        */
       public boolean evaluate(String data)
       {
          if (exprRPN.isEmpty())
          {
             return false;
          }
          Deque<Boolean> stack = new ArrayDeque<>();
          Set<String> words = words(data, !caseSensitive);
          try
          {
             for (EToken token: exprRPN)
             {
                if (token instanceof Term)
                {
                   stack.push(((Term)token).evaluate(words));
                }
                else if (token instanceof Op)
                {
                   switch ((Op)token)
                   {
                   case NOT:
                      stack.push(!stack.pop());
                      break;
                   case AND:
                      stack.push(stack.pop() & stack.pop());
                      break;
                   case OR:
                      stack.push(stack.pop() | stack.pop());
                      break;
                   }
                }
             }
             return stack.pop();
          }
          catch (EmptyStackException e)
          {
             throw new ErrorConditionException(e);
          }
       }

       /**
        * Split a string to a set of words.
        *
        * @param   data
        *          A data string with words delimited by this object's specified delimiter.
        * @param   forCaseInsensitive
        *          Return words which are unique in case-insensitive sense.
        *
        * @return  words contained in a string
        */
       public Set<String> words(String data, boolean forCaseInsensitive)
       {
          Map<String, String> words = new HashMap<>();
          if (data == null || data.trim().isEmpty())
          {
             return Collections.emptySet();
          }
          int length = data.length();
          int start = 0;
          for (int i = 0; i <= length; i++)
          {
             if (isDelimiter(data, i, length))
             {
                if (i > start)
                {
                   String word = data.substring(start, i);
                   if (!caseSensitive)
                   {
                      word = word.toUpperCase();
                   }
                   String key = forCaseInsensitive && caseSensitive ? word.toUpperCase() : word;
                   words.putIfAbsent(key, word);
                }
                start = i + 1;
             }
          }
          return new HashSet<>(words.values());
       }

       /**
        * Determines whether the character at the given index in the string should be treated as a delimiter.
        *
        * @param   data
        *          The input string to examine.
        * @param   index
        *          The current index in the string being checked.
        * @param   length
        *          The total length of the input string.
        *
        * @return  {@code true} if the character at the given index is considered a delimiter,
        *          or if the index represents end of string; {@code false} otherwise.
        */
       private boolean isDelimiter(String data, int index, int length)
       {
          if (index == length)
          {
             // end of string, treat as delimiter
             return true;
          }
          char c = data.charAt(index);
          if (c == '-' || c == '.' || c == ',')
          {
             if (index + 1 < length)
             {
                char nextChar = data.charAt(index + 1);
                return nextChar < '0' || nextChar > '9';
             }
             return true;
          }
          if (NOT_DELIMITERS.get(c))
          {
             return false;
          }
          if (DELIMITERS.get(c))
          {
             return true;
          }
          boolean matches = delimiterPattern.matcher(String.valueOf(c)).matches();
          if (matches)
          {
             DELIMITERS.set(c);
          }
          else
          {
             NOT_DELIMITERS.set(c);
          }
          return matches;
       }

       /**
        * Simple test harness for command line testing.
        *
        * @param   args
        *          Expects the first argument to be the match expression and the second to be the
        *          data to be matched.
        */
       public static void main(String[] args)
       {
          try
          {
             String expr = args[0];
    //         boolean caseSens = args.length > 2 && !"0".equals(args[2]);
             Contains contains = new Contains(expr, true, null);
             System.out.println(contains.exprRPN);
             for (int i = 1; i < args.length; i++)
             {
                String data = args[i];
                boolean match = contains.evaluate(data);
                System.out.printf("[%s]: %s\n", data, match);
             }
          }
          catch (Exception e)
          {
             LOG.severe("", e);
          }
       }
    }