CE-1646 Accept 'useCase' parameter in possibleValues function, to pass to backend, to control how possible-value filters are applied when input values are missing

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/CriteriaMissingInputValueBehavior.java

@@ -0,0 +1,66 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * 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 should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.model.actions.tables.query;
+
+
+/***************************************************************************
+ ** Possible behaviors for doing interpretValues on a filter, and a criteria
+ ** has a variable value (either as a string-that-looks-like-a-variable,
+ ** as in ${input.foreignId} for a PVS filter, or a FilterVariableExpression),
+ ** and a value for that variable isn't available.
+ **
+ ** Used in conjunction with FilterUseCase and its implementations, e.g.,
+ ** PossibleValueSearchFilterUseCase.
+ ***************************************************************************/
+public enum CriteriaMissingInputValueBehavior
+{
+   //////////////////////////////////////////////////////////////////////
+   // this was the original behavior, before we added this enum.  but, //
+   // it doesn't ever seem entirely valid, and isn't currently used.   //
+   //////////////////////////////////////////////////////////////////////
+   INTERPRET_AS_NULL_VALUE,
+
+   //////////////////////////////////////////////////////////////////////////
+   // make the criteria behave as though it's not in the filter at all.    //
+   // effectively by changing its operator to TRUE, so it always matches.  //
+   // original intended use is for possible-values on  query screens,      //
+   // where a foreign-id isn't present, so we want to show all PV options. //
+   //////////////////////////////////////////////////////////////////////////
+   REMOVE_FROM_FILTER,
+
+   //////////////////////////////////////////////////////////////////////////////////////
+   // make the criteria such that it makes no rows ever match.                         //
+   // e.g., changes it to a FALSE.  I suppose, within an OR, that might                //
+   // not be powerful enough...  but, it solves the immediate use-case in              //
+   // front of us, which is forms, where a PV field should show no values              //
+   // until a foreign key field has a value.                                           //
+   // Note that this use-case used to have the same end-effect by such                 //
+   // variables being interpreted as nulls - but this approach feels more intentional. //
+   //////////////////////////////////////////////////////////////////////////////////////
+   MAKE_NO_MATCHES,
+
+   ///////////////////////////////////////////////////////////////////////////////////////////
+   // throw an exception if a value isn't available.  This is the overall default,          //
+   // and originally was what we did for FilterVariableExpressions, e.g., for saved reports //
+   ///////////////////////////////////////////////////////////////////////////////////////////
+   THROW_EXCEPTION
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/FilterUseCase.java

@@ -0,0 +1,58 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * 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 should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.model.actions.tables.query;
+
+
+/*******************************************************************************
+ ** Interface where we can associate behaviors with various use cases for
+ ** QQueryFilters - the original being, how to handle (in the interpretValues
+ ** method) how to handle missing input values.
+ **
+ ** Includes a default implementation, with a default behavior - which is to
+ ** throw an exception upon missing criteria variable values.
+ *******************************************************************************/
+public interface FilterUseCase
+{
+   FilterUseCase DEFAULT = new DefaultFilterUseCase();
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior();
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   class DefaultFilterUseCase implements FilterUseCase
+   {
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.THROW_EXCEPTION;
+      }
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/QQueryFilter.java

@@ -528,8 +528,27 @@ public class QQueryFilter implements Serializable, Cloneable
     ** Note - it may be very important that you call this method on a clone of a
     ** QQueryFilter - e.g., if it's one that defined in metaData, and that we don't
     ** want to be (permanently) changed!!
-    *******************************************************************************/
+    **
+    ** This overload does not take in a FilterUseCase - it uses FilterUseCase.DEFAULT
+    ******************************************************************************/
    public void interpretValues(Map<String, Serializable> inputValues) throws QException
+   {
+      interpretValues(inputValues, FilterUseCase.DEFAULT);
+   }
+
+
+
+   /*******************************************************************************
+    ** Replace any criteria values that look like ${input.XXX} with the value of XXX
+    ** from the supplied inputValues map - where the handling of missing values
+    ** is specified in the inputted FilterUseCase parameter
+    **
+    ** Note - it may be very important that you call this method on a clone of a
+    ** QQueryFilter - e.g., if it's one that defined in metaData, and that we don't
+    ** want to be (permanently) changed!!
+    **
+    *******************************************************************************/
+   public void interpretValues(Map<String, Serializable> inputValues, FilterUseCase useCase) throws QException
    {
       List<Exception> caughtExceptions = new ArrayList<>();
 
@@ -545,6 +564,9 @@ public class QQueryFilter implements Serializable, Cloneable
             {
                try
                {
+                  Serializable interpretedValue = value;
+                  Exception    caughtException  = null;
+
                   if(value instanceof AbstractFilterExpression<?>)
                   {
                      ///////////////////////////////////////////////////////////////////////
@@ -553,17 +575,54 @@ public class QQueryFilter implements Serializable, Cloneable
                      ///////////////////////////////////////////////////////////////////////
                      if(value instanceof FilterVariableExpression filterVariableExpression)
                      {
-                        newValues.add(filterVariableExpression.evaluateInputValues(inputValues));
+                        try
-                     }
+                        {
-                     else
+                           interpretedValue = filterVariableExpression.evaluateInputValues(inputValues);
-                     {
+                        }
-                        newValues.add(value);
+                        catch(Exception e)
+                        {
+                           caughtException = e;
+                           interpretedValue = InputNotFound.instance;
+                        }
+                     }
+                  }
+                  else
+                  {
+                     /////////////////////////////////////////////////////////////////////////////////////////////////////////
+                     // for non-expressions, cast the value to a string, and see if it can be resolved a variable.          //
+                     // there are 3 possible cases here:                                                                    //
+                     // 1: it doesn't look like a variable, so it just comes back as a string version of whatever went in.  //
+                     // 2: it was resolved from a variable to a value, e.g., ${input.someVar} => someValue                  //
+                     // 3: it looked like a variable, but no value for that variable was present in the interpreter's value //
+                     // map - so we'll get back the InputNotFound.instance.                                                 //
+                     /////////////////////////////////////////////////////////////////////////////////////////////////////////
+                     String valueAsString = ValueUtils.getValueAsString(value);
+                     interpretedValue = variableInterpreter.interpretForObject(valueAsString, InputNotFound.instance);
+                  }
+
+                  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+                  // if interpreting a value returned the not-found value, or an empty string,                                            //
+                  // then decide how to handle the missing value, based on the use-case input                                             //
+                  // Note: questionable, using "" here, but that's what reality is passing a lot for cases we want to treat as missing... //
+                  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+                  if(interpretedValue == InputNotFound.instance || "".equals(interpretedValue))
+                  {
+                     CriteriaMissingInputValueBehavior missingInputValueBehavior = getMissingInputValueBehavior(useCase);
+
+                     switch(missingInputValueBehavior)
+                     {
+                        case REMOVE_FROM_FILTER -> criterion.setOperator(QCriteriaOperator.TRUE);
+                        case MAKE_NO_MATCHES -> criterion.setOperator(QCriteriaOperator.FALSE);
+                        case INTERPRET_AS_NULL_VALUE -> newValues.add(null);
+
+                        /////////////////////////////////////////////////
+                        // handle case in the default: THROW_EXCEPTION //
+                        /////////////////////////////////////////////////
+                        default -> throw (Objects.requireNonNullElseGet(caughtException, () -> new QUserFacingException("Missing value for criteria on field: " + criterion.getFieldName())));
                      }
                   }
                   else
                   {
-                     String       valueAsString    = ValueUtils.getValueAsString(value);
-                     Serializable interpretedValue = variableInterpreter.interpretForObject(valueAsString);
                      newValues.add(interpretedValue);
                   }
                }
@@ -586,6 +645,44 @@ public class QQueryFilter implements Serializable, Cloneable
 
 
 
+   /***************************************************************************
+    ** Note:  in the original build of this, it felt like we *might* want to be
+    ** able to specify these behaviors at the individual criteria level, where
+    ** the implementation would be to add to QFilterCriteria:
+    ** - Map<FilterUseCase, CriteriaMissingInputValueBehavior> missingInputValueBehaviors;
+    ** - CriteriaMissingInputValueBehavior getMissingInputValueBehaviorForUseCase(FilterUseCase useCase) {}
+    *
+    ** (and maybe do that in a sub-class of QFilterCriteria, so it isn't always
+    ** there?  idk...) and then here we'd call:
+    ** - CriteriaMissingInputValueBehavior missingInputValueBehavior = criterion.getMissingInputValueBehaviorForUseCase(useCase);
+    *
+    ** But, we don't actually have that use-case at hand now, so - let's keep it
+    ** just at the level we need for now.
+    **
+    ***************************************************************************/
+   private CriteriaMissingInputValueBehavior getMissingInputValueBehavior(FilterUseCase useCase)
+   {
+      if(useCase == null)
+      {
+         useCase = FilterUseCase.DEFAULT;
+      }
+
+      CriteriaMissingInputValueBehavior missingInputValueBehavior = useCase.getDefaultCriteriaMissingInputValueBehavior();
+      if(missingInputValueBehavior == null)
+      {
+         missingInputValueBehavior = useCase.getDefaultCriteriaMissingInputValueBehavior();
+      }
+
+      if(missingInputValueBehavior == null)
+      {
+         missingInputValueBehavior = FilterUseCase.DEFAULT.getDefaultCriteriaMissingInputValueBehavior();
+      }
+
+      return (missingInputValueBehavior);
+   }
+
+
+
    /*******************************************************************************
     ** Getter for skip
     *******************************************************************************/
@@ -678,4 +775,28 @@ public class QQueryFilter implements Serializable, Cloneable
    {
       return Objects.hash(criteria, orderBys, booleanOperator, subFilters, skip, limit);
    }
+
+
+
+   /***************************************************************************
+    ** "Token" object to be used as the defaultIfLooksLikeVariableButNotFound
+    ** parameter to variableInterpreter.interpretForObject, so we can be
+    ** very clear that we got this default back (e.g., instead of a null,
+    ** which could maybe mean something else?)
+    ***************************************************************************/
+   private static final class InputNotFound implements Serializable
+   {
+      private static InputNotFound instance = new InputNotFound();
+
+
+
+      /*******************************************************************************
+       ** private singleton constructor
+       *******************************************************************************/
+      private InputNotFound()
+      {
+
+      }
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/possiblevalues/PossibleValueSearchFilterUseCase.java

@@ -0,0 +1,72 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * 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 should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.model.metadata.possiblevalues;
+
+
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.CriteriaMissingInputValueBehavior;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.FilterUseCase;
+
+
+/*******************************************************************************
+ ** FilterUseCase implementation for the ways that possible value searches
+ ** are performed, and where we want to have different behaviors for criteria
+ ** that are missing an input value.  That is, either for a:
+ **
+ ** - FORM - e.g., creating a new record, or in a process - where we want a
+ ** missing filter value to basically block you from selecting a value in the
+ ** PVS field - e.g., you must enter some other foreign-key value before choosing
+ ** from this possible value - at least that's the use-case we know of now.
+ **
+ ** - FILTER - e.g., a query screen - where there isn't really quite the same
+ ** scenario of choosing that foreign-key value first - so, such a PVS should
+ ** list all its values (e.g., a criteria missing an input value should be
+ ** removed from the filter).
+ *******************************************************************************/
+public enum PossibleValueSearchFilterUseCase implements FilterUseCase
+{
+   FORM(CriteriaMissingInputValueBehavior.MAKE_NO_MATCHES),
+   FILTER(CriteriaMissingInputValueBehavior.REMOVE_FROM_FILTER);
+
+
+   private final CriteriaMissingInputValueBehavior defaultCriteriaMissingInputValueBehavior;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   PossibleValueSearchFilterUseCase(CriteriaMissingInputValueBehavior defaultCriteriaMissingInputValueBehavior)
+   {
+      this.defaultCriteriaMissingInputValueBehavior = defaultCriteriaMissingInputValueBehavior;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for defaultCriteriaMissingInputValueBehavior
+    **
+    *******************************************************************************/
+   public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+   {
+      return defaultCriteriaMissingInputValueBehavior;
+   }
+}

qqq-backend-core/src/test/java/com/kingsrook/qqq/backend/core/actions/tables/QQueryFilterTest.java

@@ -29,6 +29,8 @@ import java.util.Map;
 import com.kingsrook.qqq.backend.core.BaseTest;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.CriteriaMissingInputValueBehavior;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.FilterUseCase;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.AbstractFilterExpression;
@@ -36,9 +38,12 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.Fil
 import org.junit.jupiter.api.Test;
 import static com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator.BETWEEN;
 import static com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator.EQUALS;
+import static com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator.FALSE;
 import static com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator.IS_BLANK;
+import static com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator.TRUE;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
 
 
 /*******************************************************************************
@@ -140,4 +145,230 @@ class QQueryFilterTest extends BaseTest
       assertEquals("joinTableSomeFieldIdEquals", fve7.getVariableName());
    }
 
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void testInterpretValueVariableExpressionNotFoundUseCases() throws QException
+   {
+      Map<String, Serializable> inputValues = new HashMap<>();
+
+      AbstractFilterExpression<Serializable> expression = new FilterVariableExpression()
+         .withVariableName("clientId");
+
+      ////////////////////////////////////////
+      // Control - where the value IS found //
+      ////////////////////////////////////////
+      inputValues.put("clientId", 47);
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, expression));
+         filter.interpretValues(inputValues);
+         assertEquals(47, filter.getCriteria().get(0).getValues().get(0));
+         assertEquals(EQUALS, filter.getCriteria().get(0).getOperator());
+      }
+
+      //////////////////////////////////////////////////////
+      // now - remove the value for the next set of cases //
+      //////////////////////////////////////////////////////
+      inputValues.remove("clientId");
+
+      ////////////////////////////////////////////////////////////////////////////////////////////////
+      // a use-case that says to remove-from-filter, which, means translate to a criteria of "TRUE" //
+      ////////////////////////////////////////////////////////////////////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, expression));
+         filter.interpretValues(inputValues, new RemoveFromFilterUseCase());
+         assertEquals(0, filter.getCriteria().get(0).getValues().size());
+         assertEquals(TRUE, filter.getCriteria().get(0).getOperator());
+      }
+
+      //////////////////////////////////////////////////////////////////////////////////////////////
+      // a use-case that says to make-no-matches, which, means translate to a criteria of "FALSE" //
+      //////////////////////////////////////////////////////////////////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, expression));
+         filter.interpretValues(inputValues, new MakeNoMatchesUseCase());
+         assertEquals(0, filter.getCriteria().get(0).getValues().size());
+         assertEquals(FALSE, filter.getCriteria().get(0).getOperator());
+      }
+
+      ///////////////////////////////////////////
+      // a use-case that says to treat as null //
+      ///////////////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, expression));
+         filter.interpretValues(inputValues, new InterpretAsNullValueUseCase());
+         assertNull(filter.getCriteria().get(0).getValues().get(0));
+         assertEquals(EQUALS, filter.getCriteria().get(0).getOperator());
+      }
+
+      ///////////////////////////////////
+      // a use-case that says to throw //
+      ///////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, expression));
+         assertThatThrownBy(() -> filter.interpretValues(inputValues, new ThrowExceptionUseCase()))
+            .isInstanceOf(QUserFacingException.class)
+            .hasMessageContaining("Missing value for variable: clientId");
+      }
+
+      //////////////////////////////////////////////////////////
+      // verify that empty-string is treated as not-found too //
+      //////////////////////////////////////////////////////////
+      inputValues.put("clientId", "");
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, expression));
+         assertThatThrownBy(() -> filter.interpretValues(inputValues, new ThrowExceptionUseCase()))
+            .isInstanceOf(QUserFacingException.class)
+            .hasMessageContaining("Missing value for criteria on field: id");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void testInterpretValueStringStyleNotFoundUseCases() throws QException
+   {
+      Map<String, Serializable> inputValues = new HashMap<>();
+
+      ////////////////////////////////////////
+      // Control - where the value IS found //
+      ////////////////////////////////////////
+      inputValues.put("clientId", 47);
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, "${input.clientId}"));
+         filter.interpretValues(inputValues);
+         assertEquals(47, filter.getCriteria().get(0).getValues().get(0));
+         assertEquals(EQUALS, filter.getCriteria().get(0).getOperator());
+      }
+
+      //////////////////////////////////////////////////////
+      // now - remove the value for the next set of cases //
+      //////////////////////////////////////////////////////
+      inputValues.remove("clientId");
+
+      ////////////////////////////////////////////////////////////////////////////////////////////////
+      // a use-case that says to remove-from-filter, which, means translate to a criteria of "TRUE" //
+      ////////////////////////////////////////////////////////////////////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, "${input.clientId}"));
+         filter.interpretValues(inputValues, new RemoveFromFilterUseCase());
+         assertEquals(0, filter.getCriteria().get(0).getValues().size());
+         assertEquals(TRUE, filter.getCriteria().get(0).getOperator());
+      }
+
+      //////////////////////////////////////////////////////////////////////////////////////////////
+      // a use-case that says to make-no-matches, which, means translate to a criteria of "FALSE" //
+      //////////////////////////////////////////////////////////////////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, "${input.clientId}"));
+         filter.interpretValues(inputValues, new MakeNoMatchesUseCase());
+         assertEquals(0, filter.getCriteria().get(0).getValues().size());
+         assertEquals(FALSE, filter.getCriteria().get(0).getOperator());
+      }
+
+      ///////////////////////////////////////////
+      // a use-case that says to treat as null //
+      ///////////////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, "${input.clientId}"));
+         filter.interpretValues(inputValues, new InterpretAsNullValueUseCase());
+         assertNull(filter.getCriteria().get(0).getValues().get(0));
+         assertEquals(EQUALS, filter.getCriteria().get(0).getOperator());
+      }
+
+      ///////////////////////////////////
+      // a use-case that says to throw //
+      ///////////////////////////////////
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, "${input.clientId}"));
+         assertThatThrownBy(() -> filter.interpretValues(inputValues, new ThrowExceptionUseCase()))
+            .isInstanceOf(QUserFacingException.class)
+            .hasMessageContaining("Missing value for criteria on field: id");
+      }
+
+      //////////////////////////////////////////////////////////
+      // verify that empty-string is treated as not-found too //
+      //////////////////////////////////////////////////////////
+      inputValues.put("clientId", "");
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("id", EQUALS, "${input.clientId}"));
+         assertThatThrownBy(() -> filter.interpretValues(inputValues, new ThrowExceptionUseCase()))
+            .isInstanceOf(QUserFacingException.class)
+            .hasMessageContaining("Missing value for criteria on field: id");
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class RemoveFromFilterUseCase implements FilterUseCase
+   {
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.REMOVE_FROM_FILTER;
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class MakeNoMatchesUseCase implements FilterUseCase
+   {
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.MAKE_NO_MATCHES;
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class InterpretAsNullValueUseCase implements FilterUseCase
+   {
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.INTERPRET_AS_NULL_VALUE;
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class ThrowExceptionUseCase implements FilterUseCase
+   {
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.THROW_EXCEPTION;
+      }
+   }
 }

qqq-middleware-javalin/src/main/java/com/kingsrook/qqq/backend/javalin/QJavalinImplementation.java

@@ -114,6 +114,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldAdornment;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.core.model.metadata.frontend.QFrontendVariant;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.PossibleValueSearchFilterUseCase;
 import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -125,6 +126,7 @@ import com.kingsrook.qqq.backend.core.modules.authentication.implementations.Aut
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.ExceptionUtils;
 import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import com.kingsrook.qqq.backend.core.utils.ObjectUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 import com.kingsrook.qqq.backend.core.utils.collections.MapBuilder;
@@ -1792,7 +1794,11 @@ public class QJavalinImplementation
          }
 
          defaultQueryFilter = field.getPossibleValueSourceFilter().clone();
-         defaultQueryFilter.interpretValues(values);
+
+         String                           useCaseParam = QJavalinUtils.getQueryParamOrFormParam(context, "useCase");
+         PossibleValueSearchFilterUseCase useCase      = ObjectUtils.tryElse(() -> PossibleValueSearchFilterUseCase.valueOf(useCaseParam.toUpperCase()), PossibleValueSearchFilterUseCase.FORM);
+
+         defaultQueryFilter.interpretValues(values, useCase);
       }
 
       finishPossibleValuesRequest(context, field.getPossibleValueSourceName(), defaultQueryFilter);

qqq-middleware-javalin/src/test/java/com/kingsrook/qqq/backend/javalin/QJavalinImplementationTest.java

@@ -950,24 +950,138 @@ class QJavalinImplementationTest extends QJavalinTestBase
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private JSONArray assertPossibleValueSuccessfulResponseAndGetOptionsArray(HttpResponse<String> response)
+   {
+      assertEquals(200, response.getStatus());
+      JSONObject jsonObject = JsonUtils.toJSONObject(response.getBody());
+      assertNotNull(jsonObject);
+      return (jsonObject.getJSONArray("options"));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void assertPossibleValueSuccessfulResponseWithNoOptions(HttpResponse<String> response)
+   {
+      assertEquals(200, response.getStatus());
+      JSONObject jsonObject = JsonUtils.toJSONObject(response.getBody());
+      assertNotNull(jsonObject);
+      assertFalse(jsonObject.has("options")); // no results comes back as result w/o options array.
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
    @Test
    void testPossibleValueWithFilter()
    {
+      /////////////////////////////////////////////////////////////
+      // post with no search term, and values that find a result //
+      /////////////////////////////////////////////////////////////
       HttpResponse<String> response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=")
          .field("values", """
-         {"email":"tsamples@mmltholdings.com"}
+            {"email":"tsamples@mmltholdings.com"}
-         """)
+            """)
          .asString();
 
-      assertEquals(200, response.getStatus());
+      JSONArray options = assertPossibleValueSuccessfulResponseAndGetOptionsArray(response);
-      JSONObject jsonObject = JsonUtils.toJSONObject(response.getBody());
+      assertNotNull(options);
-      assertNotNull(jsonObject);
+      assertEquals(1, options.length());
-      assertNotNull(jsonObject.getJSONArray("options"));
+      assertEquals("Tyler Samples (4)", options.getJSONObject(0).getString("label"));
-      assertEquals(1, jsonObject.getJSONArray("options").length());
+
-      assertEquals("Tyler Samples (4)", jsonObject.getJSONArray("options").getJSONObject(0).getString("label"));
+      ///////////////////////////////////////////////////////////
+      // post with search term and values that find no results //
+      ///////////////////////////////////////////////////////////
+      response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=notFound")
+         .field("values", """
+            {"email":"tsamples@mmltholdings.com"}
+            """)
+         .asString();
+      assertPossibleValueSuccessfulResponseWithNoOptions(response);
+
+      ////////////////////////////////////////////////////////////////
+      // post with no search term, but values that cause no matches //
+      ////////////////////////////////////////////////////////////////
+      response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=")
+         .field("values", """
+            {"email":"noUser@mmltholdings.com"}
+            """)
+         .asString();
+      assertPossibleValueSuccessfulResponseWithNoOptions(response);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void testPossibleValueWithFilterMissingValue()
+   {
+      /////////////////////////////////////////////////////////////
+      // filter use-case, with no values, should return options. //
+      /////////////////////////////////////////////////////////////
+      HttpResponse<String> response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=filter").asString();
+      JSONArray options = assertPossibleValueSuccessfulResponseAndGetOptionsArray(response);
+      assertNotNull(options);
+      assertThat(options.length()).isGreaterThanOrEqualTo(5);
+
+      ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // similarly, values map, but not the 'email' value, that this PVS field is based on, should return options. //
+      ///////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=filter")
+         .field("values", """
+            {"userId":"123"}
+            """)
+         .asString();
+      options = assertPossibleValueSuccessfulResponseAndGetOptionsArray(response);
+      assertNotNull(options);
+      assertThat(options.length()).isGreaterThanOrEqualTo(5);
+
+      ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // similarly, values map, with the email value, but an empty string in there - should act the same as if it's missing, and not filter the values. //
+      ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=filter")
+         .field("values", """
+            {"email":""}
+            """)
+         .asString();
+      options = assertPossibleValueSuccessfulResponseAndGetOptionsArray(response);
+      assertNotNull(options);
+      assertThat(options.length()).isGreaterThanOrEqualTo(5);
+
+      /////////////////////////////////////////////////////////////////////////
+      // versus form use-case with no values, which should return 0 options. //
+      /////////////////////////////////////////////////////////////////////////
+      response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=form").asString();
+      assertPossibleValueSuccessfulResponseWithNoOptions(response);
+
+      /////////////////////////////////////////////////////////////////////////////////
+      // versus form use-case with expected value, which should return some options. //
+      /////////////////////////////////////////////////////////////////////////////////
+      response = Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=form")
+         .field("values", """
+            {"email":"tsamples@mmltholdings.com"}
+            """)
+         .asString();
+      options = assertPossibleValueSuccessfulResponseAndGetOptionsArray(response);
+      assertNotNull(options);
+      assertEquals(1, options.length());
+      assertEquals("Tyler Samples (4)", options.getJSONObject(0).getString("label"));
+
+      ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // finally an unrecognized useCase (or missing or empty), should behave the same as a form, and return 0 options if the filter-value is missing. //
+      ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      assertPossibleValueSuccessfulResponseWithNoOptions(Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=notAUseCase").asString());
+      assertPossibleValueSuccessfulResponseWithNoOptions(Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=").asString());
+      assertPossibleValueSuccessfulResponseWithNoOptions(Unirest.post(BASE_URL + "/data/pet/possibleValues/ownerPersonId?searchTerm=&useCase=").asString());
    }