Add parquet read TableDefinition support (#4831)

Additionally, adds explicit entry points for single, flat-partitioned, and kv-partitioned reads.

Fixes #4746
Partial workaround for #871

engine/table/src/main/java/io/deephaven/engine/table/impl/SourceTable.java

@@ -113,6 +113,11 @@ private void initialize() {
         initializeLocationSizes();
     }
 
+    @TestUseOnly
+    public final TableLocationProvider tableLocationProvider() {
+        return locationProvider;
+    }
+
     /**
      * This is only for unit tests, at this time.
      */

engine/table/src/main/java/io/deephaven/engine/table/impl/locations/TableLocationProvider.java

@@ -77,7 +77,7 @@ interface Listener extends BasicTableDataListener {
     void unsubscribe(@NotNull Listener listener);
 
     /**
-     * Initialize or run state information about the list of existing locations.
+     * Initialize or refresh state information about the list of existing locations.
      */
     void refresh();
 

engine/table/src/main/java/io/deephaven/engine/table/impl/locations/impl/KnownLocationKeyFinder.java

@@ -9,6 +9,7 @@
 import java.util.Arrays;
 import java.util.Comparator;
 import java.util.List;
+import java.util.Optional;
 import java.util.function.Consumer;
 
 /**
@@ -34,18 +35,31 @@ public static <TLK extends ImmutableTableLocationKey> KnownLocationKeyFinder<TLK
         if (comparator != null) {
             mutableKeys.sort(comparator);
         }
-        return new KnownLocationKeyFinder<>(mutableKeys);
+        final String comparatorString = comparator == null
+                ? null
+                : Comparator.naturalOrder().equals(comparator)
+                        ? "Comparator.naturalOrder()"
+                        : comparator.toString();
+        final String toString =
+                String.format("%s[%s, %s]", KnownLocationKeyFinder.class.getSimpleName(), finder, comparatorString);
+        return new KnownLocationKeyFinder<>(mutableKeys, toString);
     }
 
     private final List<TLK> knownKeys;
+    private final String toString;
 
     @SafeVarargs
     public KnownLocationKeyFinder(@NotNull final TLK... knownKeys) {
         this(Arrays.asList(knownKeys));
     }
 
     public KnownLocationKeyFinder(List<TLK> knownKeys) {
+        this(knownKeys, null);
+    }
+
+    public KnownLocationKeyFinder(List<TLK> knownKeys, String toString) {
         this.knownKeys = List.copyOf(knownKeys);
+        this.toString = toString;
     }
 
     /**
@@ -55,8 +69,21 @@ public List<TLK> getKnownKeys() {
         return knownKeys;
     }
 
+    public Optional<TLK> getFirstKey() {
+        return knownKeys.isEmpty() ? Optional.empty() : Optional.of(knownKeys.get(0));
+    }
+
+    public Optional<TLK> getLastKey() {
+        return knownKeys.isEmpty() ? Optional.empty() : Optional.of(knownKeys.get(knownKeys.size() - 1));
+    }
+
     @Override
     public void findKeys(@NotNull Consumer<TLK> locationKeyObserver) {
         knownKeys.forEach(locationKeyObserver);
     }
+
+    @Override
+    public String toString() {
+        return toString == null ? super.toString() : toString;
+    }
 }