fix: Subscribing to an uncoalesced table must not make it seem coales…

…ced (#6211)

Updated and clarified JS API documentation for this topic.

Fixes #6210

web/client-api/src/main/java/io/deephaven/web/client/api/Column.java

@@ -179,11 +179,10 @@ public Integer getStyleColumnIndex() {
  }
 
  /**
- * True if this column is a partition column. Partition columns are used for filtering uncoalesced tables (see
- * <b>isUncoalesced</b> property on <b>Table</b>)
- *
- * @return boolean
+ * True if this column is a partition column. Partition columns are used for filtering uncoalesced tables - see
+ * {@link JsTable#isUncoalesced()}.
  *
+ * @return true if the column is a partition column
  */
  @JsProperty
  public boolean getIsPartitionColumn() {

web/client-api/src/main/java/io/deephaven/web/client/api/JsTable.java

@@ -88,10 +88,10 @@
  */
 @TsName(namespace = "dh", name = "Table")
 public class JsTable extends HasLifecycle implements HasTableBinding, JoinableTable, ServerObject {
- @JsProperty(namespace = "dh.Table")
  /**
  * The table size has updated, so live scrollbars and the like can be updated accordingly.
  */
+ @JsProperty(namespace = "dh.Table")
  public static final String EVENT_SIZECHANGED = "sizechanged",
  /**
  * event.detail is the currently visible window, the same as if getViewportData() was called and resolved.
@@ -136,6 +136,9 @@ public class JsTable extends HasLifecycle implements HasTableBinding, JoinableTa
  EVENT_REQUEST_FAILED = "requestfailed",
  EVENT_REQUEST_SUCCEEDED = "requestsucceeded";
 
+ /**
+ * The size the table will have if it is uncoalesced.
+ */
  @JsProperty(namespace = "dh.Table")
  public static final double SIZE_UNCOALESCED = -2;
 
@@ -438,11 +441,14 @@ public JsLayoutHints getLayoutHints() {
  }
 
  /**
- * The total count of rows in the table. The size can and will change; see the <b>sizechanged</b> event for details.
- * Size will be negative in exceptional cases (e.g., the table is uncoalesced; see the <b>isUncoalesced</b>
- * property). for details).
- * 
- * @return double
+ * The total count of rows in the table. If there is a viewport subscription active, this size will be updated when
+ * the subscription updates. If not, and {@link #isUncoalesced()} is true, the size will be
+ * {@link #SIZE_UNCOALESCED}. Otherwise, the size will be updated when the server's update graph processes changes.
+ * <p>
+ * When the size changes, the {@link #EVENT_SIZECHANGED} event will be fired.
+ *
+ * @return the size of the table, or {@link #SIZE_UNCOALESCED} if there is no subscription and the table is
+ * uncoalesced.
  */
  @JsProperty
  public double getSize() {
@@ -465,12 +471,11 @@ public String getDescription() {
  }
 
  /**
- * The total count of the rows in the table, excluding any filters. Unlike <b>size</b>, changes to this value will
- * not result in any event. <b>Sort[] sort</b> an ordered list of Sorts to apply to the table. To update, call
- * applySort(). Note that this getter will return the new value immediately, even though it may take a little time
- * to update on the server. You may listen for the <b>sortchanged</b> event to know when to update the UI.
+ * The total count of the rows in the table, excluding any filters. Unlike {@link #getSize()}, changes to this value
+ * will not result in any event. If the table is unfiltered, this will return the same size as {@link #getSize()}.
+ * If this table was uncoalesced before it was filtered, this will return {@link #SIZE_UNCOALESCED}.
  * 
- * @return double
+ * @return the size of the table before filters, or {@link #SIZE_UNCOALESCED}
  */
  @JsProperty
  public double getTotalSize() {
@@ -1522,11 +1527,15 @@ public boolean isRefreshing() {
  }
 
  /**
- * Read-only. True if this table is uncoalesced. Set a viewport or filter on the partition columns to coalesce the
- * table. Check the <b>isPartitionColumn</b> property on the table columns to retrieve the partition columns. Size
- * will be unavailable until table is coalesced.
- * 
- * @return boolean
+ * Read-only. True if this table is uncoalesced, indicating that work must be done before the table can be used.
+ * <p>
+ * Uncoalesced tables are expensive to operate on - filter to a single partition or range of partitions before
+ * subscribing to access only the desired data efficiently. A subscription can be specified without a filter, but
+ * this can be very expensive. To see which partitions are available, check each column on the table to see which
+ * have {@link Column#getIsPartitionColumn()} as {@code true}, and filter those columns. To read the possible values
+ * for those columns, use {@link #selectDistinct(Column[])}.
+ *
+ * @return True if the table is uncoaleced and should be filtered before operating on it, otherwise false.
  */
  @JsProperty(name = "isUncoalesced")
  public boolean isUncoalesced() {

web/client-api/src/main/java/io/deephaven/web/client/state/ClientTableState.java

@@ -426,6 +426,10 @@ public long getSize() {
  }
 
  public void setSize(long size) {
+ if (this.size == Long.MIN_VALUE) {
+ // Table is uncoalesced, ignore size change
+ return;
+ }
  boolean log = this.size != size;
  if (log) {
  JsLog.debug("CTS", this, " set size; was ", this.size, " is now ", size);