Merge pull request #401 from QRun-IO/feature/tiebreak-meta-data-producer-sort-by-name

darinkelkhoff · web-flow · commit 95e34eead9e9 · 2026-02-17T15:58:15.000-06:00
fix(metaDataProduction): add class simple name as a tie-breaker when …
diff --git a/qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/MetaDataProducerHelper.java b/qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/MetaDataProducerHelper.java
@@ -57,7 +57,18 @@
 
 
 /*******************************************************************************
- ** Help work with MetaDataProducers.
+ * Help work with MetaDataProducers.
+ *
+ * <p>Note that all of the public methods here use {@code sortMetaDataProducers},
+ * which by default will sort by the sortOrder specified in the producer objects,
+ * then by the type that they return, and finally by their class simple name, then
+ * full name.</p>
+ *
+ * <p>But - this sorting by class names was added in 0.40.0. Prior to that,
+ * there was no tie breaker on the sort.  To restore the previous behavior, set
+ * the system property {@code qqq.MetaDataProducerHelper.disableNameTiebreaker}
+ * to {@code true}.</p>
+ *
  *******************************************************************************/
 public class MetaDataProducerHelper
 {
@@ -66,10 +77,12 @@ public class MetaDataProducerHelper
    private static Map<Class<?>, Integer> comparatorValuesByType = new HashMap<>();
    private static Integer                defaultComparatorValue;
 
+   private static boolean didLogAboutDisabledTiebreaker = false;
+
    static
    {
       ////////////////////////////////////////////////////////////////////////////////////////
-      // define how we break ties in sort-order based on the meta-dta type.  e.g., do apps  //
+      // define how we break ties in sort-order based on the meta-data type.  e.g., do apps //
       // after all other types (as apps often try to get other types from the instance)     //
       // also - do backends earlier than others (e.g., tables may expect backends to exist) //
       // any types not in the map get the default value.                                    //
@@ -111,6 +124,7 @@ public static void processAllMetaDataProducersInPackage(QInstance instance, Stri
    }
 
 
+
    /***************************************************************************
     **
     ***************************************************************************/
@@ -190,11 +204,18 @@ public static List<MetaDataProducerInterface<?>> findProducers(String packageNam
 
 
    /***************************************************************************
-    **
+    * sort a list of producers: First by the sortOrder specified in the producer objects.
+    * Second based on their types, so kinds that depend on other kinds come later.
+    * Third, by class simple name, and 4th by full class name, to give stable ordering
+    * (unless opt'ed out by system property).
+    *
+    * <p>Note, we use simple name before full name, in case, for some reason, you
+    * wanted to control the sort by naming your classes a certain way - easier
+    * to change Simple names than packages.</p>
     ***************************************************************************/
    public static void sortMetaDataProducers(List<MetaDataProducerInterface<?>> producers)
    {
-      producers.sort(Comparator
+      Comparator<MetaDataProducerInterface<?>> comparator = Comparator
          .comparing((MetaDataProducerInterface<?> p) -> p.getSortOrder())
          .thenComparing((MetaDataProducerInterface<?> p) ->
          {
@@ -207,7 +228,32 @@ public static void sortMetaDataProducers(List<MetaDataProducerInterface<?>> prod
             {
                return (0);
             }
-         }));
+         });
+
+      //////////////////////////////////////////////////////////////////////////
+      // read this system property each time this method is called.           //
+      // normally we might read it once into a static var - but, e.g., tests  //
+      // might need to change the value over time.  and this isn't a hot code //
+      // path at all, so we can bear the cost each time we're called in here. //
+      //////////////////////////////////////////////////////////////////////////
+      String  propertyName          = "qqq.MetaDataProducerHelper.disableNameTiebreaker";
+      boolean disableNameTiebreaker = Boolean.getBoolean(propertyName);
+      if(disableNameTiebreaker)
+      {
+         if(!didLogAboutDisabledTiebreaker)
+         {
+            didLogAboutDisabledTiebreaker = true;
+            LOG.warn("Name tiebreaker is disabled for MetaDataProducerHelper.sortMetaDataProducers.  This is legacy behavior, activated by system property [" + propertyName + "], which may be removed in a future release.");
+         }
+      }
+      else
+      {
+         comparator = comparator
+            .thenComparing(p -> p.getClass().getSimpleName())
+            .thenComparing(p -> p.getClass().getName());
+      }
+
+      producers.sort(comparator);
    }
 
 
@@ -387,8 +433,8 @@ private static MetaDataProducerInterface<?> processChildRecordListWidget(Class<?
       String                         parentTableName  = getTableNameStaticFieldValue(sourceClass);
       String                         childTableName   = getTableNameStaticFieldValue(childEntityClass);
 
-      ChildRecordListWidget childRecordListWidget = childTable.childRecordListWidget();
-      ChildRecordListWidgetFromRecordEntityGenericMetaDataProducer producer = new ChildRecordListWidgetFromRecordEntityGenericMetaDataProducer(childTableName, parentTableName, childRecordListWidget);
+      ChildRecordListWidget                                        childRecordListWidget = childTable.childRecordListWidget();
+      ChildRecordListWidgetFromRecordEntityGenericMetaDataProducer producer              = new ChildRecordListWidgetFromRecordEntityGenericMetaDataProducer(childTableName, parentTableName, childRecordListWidget);
       producer.setSourceClass(sourceClass);
       return producer;
    }
diff --git a/qqq-backend-core/src/test/java/com/kingsrook/qqq/backend/core/model/metadata/MetaDataProducerHelperTest.java b/qqq-backend-core/src/test/java/com/kingsrook/qqq/backend/core/model/metadata/MetaDataProducerHelperTest.java
@@ -22,6 +22,8 @@
 package com.kingsrook.qqq.backend.core.model.metadata;
 
 
+import java.util.ArrayList;
+import java.util.List;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
@@ -40,6 +42,7 @@
 import com.kingsrook.qqq.backend.core.model.metadata.producers.TestNoInterfacesExtendsObject;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.TestNoValidConstructorMetaDataProducer;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
@@ -52,6 +55,20 @@
  *******************************************************************************/
 class MetaDataProducerHelperTest
 {
+   private static final String DISABLE_NAME_TIEBREAKER_PROPERTY = "qqq.MetaDataProducerHelper.disableNameTiebreaker";
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   @AfterEach
+   void afterEach()
+   {
+      System.clearProperty(DISABLE_NAME_TIEBREAKER_PROPERTY);
+   }
+
+
 
    /*******************************************************************************
     **
@@ -122,4 +139,180 @@ void test() throws QException
 
    }
 
+
+
+   /*******************************************************************************
+    ** Test that producers with the same sortOrder and type are sorted by class
+    ** simple name (alphabetically), then by full class name, for deterministic ordering.
+    *******************************************************************************/
+   @Test
+   void testSortByClassSimpleNameThenFullName()
+   {
+      ///////////////////////////////////////////////////////////////////////////
+      // create producers with same sortOrder - they should sort by class name //
+      ///////////////////////////////////////////////////////////////////////////
+      MetaDataProducerInterface<?> producerZ = new TestProducerZebra();
+      MetaDataProducerInterface<?> producerA = new TestProducerAlpha();
+      MetaDataProducerInterface<?> producerM = new TestProducerMango();
+
+      ///////////////////////////////////////////////////////
+      // put them in an "unsorted" order and sort the list //
+      ///////////////////////////////////////////////////////
+      List<MetaDataProducerInterface<?>> producers = new ArrayList<>(List.of(producerZ, producerA, producerM));
+      MetaDataProducerHelper.sortMetaDataProducers(producers);
+
+      //////////////////////////////////////////////////////////////
+      // verify they are now sorted alphabetically by simple name //
+      //////////////////////////////////////////////////////////////
+      assertEquals("TestProducerAlpha", producers.get(0).getClass().getSimpleName());
+      assertEquals("TestProducerMango", producers.get(1).getClass().getSimpleName());
+      assertEquals("TestProducerZebra", producers.get(2).getClass().getSimpleName());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test that the system property disables the class name tiebreaker, restoring
+    ** the previous (undefined) behavior.
+    *******************************************************************************/
+   @Test
+   void testDisableNameTiebreakerSystemProperty()
+   {
+      System.setProperty(DISABLE_NAME_TIEBREAKER_PROPERTY, "true");
+
+      MetaDataProducerInterface<?> producerZ = new TestProducerZebra();
+      MetaDataProducerInterface<?> producerA = new TestProducerAlpha();
+
+      /////////////////////////////////////////////////////////////////////////////
+      // with tiebreaker disabled, order should be based on insertion order      //
+      // (since sortOrder and type are equal, and no further comparator applied) //
+      /////////////////////////////////////////////////////////////////////////////
+      List<MetaDataProducerInterface<?>> producers = new ArrayList<>(List.of(producerZ, producerA));
+      MetaDataProducerHelper.sortMetaDataProducers(producers);
+
+      //////////////////////////////////////////////////////////////////////////////
+      // the order should remain as inserted (Z, A) since there's no tie-breaker. //
+      // note: this relies on stable sort behavior in Java                        //
+      //////////////////////////////////////////////////////////////////////////////
+      assertEquals("TestProducerZebra", producers.get(0).getClass().getSimpleName());
+      assertEquals("TestProducerAlpha", producers.get(1).getClass().getSimpleName());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test that sortOrder still takes precedence over class name.
+    *******************************************************************************/
+   @Test
+   void testSortOrderTakesPrecedenceOverClassName()
+   {
+      ///////////////////////////////////////////////////////////////////////////
+      // producerZ has lower sortOrder, so should come first despite "Z" > "A" //
+      ///////////////////////////////////////////////////////////////////////////
+      MetaDataProducerInterface<?> producerZ = new TestProducerZebra()
+      {
+         @Override
+         public int getSortOrder()
+         {
+            return 100;
+         }
+      };
+      MetaDataProducerInterface<?> producerA = new TestProducerAlpha()
+      {
+         @Override
+         public int getSortOrder()
+         {
+            return 200;
+         }
+      };
+
+      List<MetaDataProducerInterface<?>> producers = new ArrayList<>(List.of(producerA, producerZ));
+      MetaDataProducerHelper.sortMetaDataProducers(producers);
+
+      //////////////////////////////////////////////////////////////
+      // Z should come first because it has lower sortOrder (100) //
+      //////////////////////////////////////////////////////////////
+      assertEquals(100, producers.get(0).getSortOrder());
+      assertEquals(200, producers.get(1).getSortOrder());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test that when simple names are equal, full class name is used as tiebreaker.
+    ** This tests the scenario mentioned in the review: com.foo.MyProducer vs com.bar.MyProducer
+    *******************************************************************************/
+   @Test
+   void testFullClassNameTiebreakerWhenSimpleNamesMatch()
+   {
+      /////////////////////////////////////////////////////////////////////////////////
+      // create two producers from different inner classes that have the same simple //
+      // name pattern (anonymous classes extending the same base)                    //
+      // We'll use the outer class structure to create predictable full names        //
+      /////////////////////////////////////////////////////////////////////////////////
+      MetaDataProducerInterface<?> producerFromAlpha = new TestProducerAlpha() {};
+      MetaDataProducerInterface<?> producerFromZebra = new TestProducerZebra() {};
+
+      //////////////////////////////////////////////////////////////////////////////
+      // both are anonymous classes, so their simple names will be empty strings. //
+      // the full name will include the outer class and a number suffix.          //
+      // this exercises the full-name tiebreaker when simple names are equal.     //
+      //////////////////////////////////////////////////////////////////////////////
+      assertEquals(producerFromAlpha.getClass().getSimpleName(), producerFromZebra.getClass().getSimpleName());
+
+      List<MetaDataProducerInterface<?>> producers = new ArrayList<>(List.of(producerFromZebra, producerFromAlpha));
+      MetaDataProducerHelper.sortMetaDataProducers(producers);
+
+      /////////////////////////////////////////////////////////////////////////////////////
+      // after sorting, they should be in a deterministic order based on full class name //
+      // the key assertion is that sorting is stable and deterministic                   //
+      /////////////////////////////////////////////////////////////////////////////////////
+      String firstName  = producers.get(0).getClass().getName();
+      String secondName = producers.get(1).getClass().getName();
+      assertTrue(firstName.compareTo(secondName) <= 0,
+         "Expected first producer's full name [" + firstName + "] to sort before or equal to second [" + secondName + "]");
+   }
+
+
+
+   /***************************************************************************
+    * Test producer class - named to sort first alphabetically
+    ***************************************************************************/
+   private static class TestProducerAlpha implements MetaDataProducerInterface<QTableMetaData>
+   {
+      @Override
+      public QTableMetaData produce(QInstance qInstance)
+      {
+         return new QTableMetaData().withName("alpha");
+      }
+   }
+
+
+
+   /***************************************************************************
+    * Test producer class - named to sort in the middle alphabetically
+    ***************************************************************************/
+   private static class TestProducerMango implements MetaDataProducerInterface<QTableMetaData>
+   {
+      @Override
+      public QTableMetaData produce(QInstance qInstance)
+      {
+         return new QTableMetaData().withName("mango");
+      }
+   }
+
+
+
+   /***************************************************************************
+    * Test producer class - named to sort last alphabetically
+    ***************************************************************************/
+   private static class TestProducerZebra implements MetaDataProducerInterface<QTableMetaData>
+   {
+      @Override
+      public QTableMetaData produce(QInstance qInstance)
+      {
+         return new QTableMetaData().withName("zebra");
+      }
+   }
+
 }
