Skip to content

Commit

Permalink
JS API member/documentation cleanup (deephaven#4787)
Browse files Browse the repository at this point in the history
  • Loading branch information
niloc132 authored Nov 16, 2023
1 parent a52c2fe commit 11537f0
Show file tree
Hide file tree
Showing 4 changed files with 40 additions and 32 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -386,9 +386,8 @@ public String[] getAttributes() {
}

/**
* null if no property exists, a string if it is an easily serializable property, or a <b>Promise
* <Table>
* </b> that will either resolve with a table or error out if the object can't be passed to JS.
* null if no property exists, a string if it is an easily serializable property, or a {@code Promise
* &lt;Table&gt;} that will either resolve with a table or error out if the object can't be passed to JS.
*
* @param attributeName
* @return Object
Expand Down Expand Up @@ -877,7 +876,7 @@ public Promise<JsTotalsTable> getTotalsTable(
*
* @return dh.TotalsTableConfig
*/
@JsMethod
@JsProperty
public JsTotalsTableConfig getTotalsTableConfig() {
// we want to communicate to the JS dev that there is no default config, so we allow
// returning null here, rather than a default config. They can then easily build a
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@
import io.deephaven.web.client.api.Column;
import io.deephaven.web.client.api.DateWrapper;
import io.deephaven.web.client.api.LongWrapper;
import io.deephaven.web.client.api.TableData;
import io.deephaven.web.client.api.i18n.JsTimeZone;
import javaemul.internal.annotations.DoNotAutobox;
import jsinterop.annotations.JsIgnore;
import jsinterop.annotations.JsMethod;
Expand Down Expand Up @@ -101,12 +103,13 @@ public static FilterValue ofNumber(double input) {

/**
* Constructs a number for the filter API from the given parameter. Can also be used on the values returned from
* <b><Row.get/b> for DateTime values. To create a filter with a date, use <b>dh.DateWrapper.ofJsDate</b> or
* <b>dh.i18n.DateTimeFormat.parse</b>. To create a filter with a 64-bit long integer, use
* <b>dh.LongWrapper.ofString</b>.
* {@link io.deephaven.web.client.api.TableData.Row#get(TableData.RowPositionUnion)} for DateTime values. To create
* a filter with a date, use <b>dh.DateWrapper.ofJsDate</b> or
* {@link io.deephaven.web.client.api.i18n.JsDateTimeFormat#parse(String, JsTimeZone)}. To create a filter with a
* 64-bit long integer, use {@link LongWrapper#ofString(String)}.
*
* @param input
* @return
* @param input the number to wrap as a FilterValue
* @return an immutable FilterValue that can be built into a filter
*/
public static FilterValue ofNumber(OfNumberUnionParam input) {
Objects.requireNonNull(input);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,39 +71,44 @@
import static io.deephaven.web.client.api.subscription.ViewportData.NO_ROW_FORMAT_COLUMN;

/**
* Behaves like a JsTable externally, but data, state, and viewports are managed by an entirely different mechanism, and
* so reimplemented here.
*
* Behaves like a {@link JsTable} externally, but data, state, and viewports are managed by an entirely different
* mechanism, and so reimplemented here.
* <p>
* Any time a change is made, we build a new request and send it to the server, and wait for the updated state.
*
* <p>
* Semantics around getting updates from the server are slightly different - we don't "unset" the viewport here after
* operations are performed, but encourage the client code to re-set them to the desired position.
*
* <p>
* The table size will be -1 until a viewport has been fetched.
*
* <p>
* Similar to a table, a Tree Table provides access to subscribed viewport data on the current hierarchy. A different
* Row type is used within that viewport, showing the depth of that node within the tree and indicating details about
* whether or not it has children or is expanded. The Tree Table itself then provides the ability to change if a row is
* whether it has children or is expanded. The Tree Table itself then provides the ability to change if a row is
* expanded or not. Methods used to control or check if a row should be expanded or not can be invoked on a TreeRow
* instance, or on the number of the row (thus allowing for expanding/collapsing rows which are not currently visible in
* the viewport).
*
* Events and viewports are somewhat different than tables, due to the expense of computing the expanded/collapsed rows
* <p>
* Events and viewports are somewhat different from tables, due to the expense of computing the expanded/collapsed rows
* and count of children at each level of the hierarchy, and differences in the data that is available.
*
* - There is no <b>totalSize</b> property. - The viewport is not un-set when changes are made to filter or sort, but
* changes will continue to be streamed in. It is suggested that the viewport be changed to the desired position
* (usually the first N rows) after any filter/sort change is made. Likewise, <b>getViewportData()</b> will always
* return the most recent data, and will not wait if a new operation is pending. - Custom columns are not directly
* supported. If the <b>TreeTable</b> was created client-side, the original Table can have custom columns applied, and
* the <b>TreeTable</b> can be recreated. - The <b>totalsTableConfig</b> property is instead a method, and returns a
* promise so the config can be fetched asynchronously. - Totals Tables for trees vary in behavior between hierarchical
* tables and roll-up tables. This behavior is based on the original flat table used to produce the Tree Table - for a
* hierarchical table (i.e. Table.treeTable in the query config), the totals will include non-leaf nodes (since they are
* themselves actual rows in the table), but in a roll-up table, the totals only include leaf nodes (as non-leaf nodes
* are generated through grouping the contents of the original table). Roll-ups also have the
* <b>isIncludeConstituents</b> property, indicating that a <b>Column</b> in the tree may have a <b>constituentType</b>
* property reflecting that the type of cells where <b>hasChildren</b> is false will be different from usual.
* <p>
* <ul>
* <li>There is no {@link JsTable#getTotalSize() totalSize} property.</li>
* <li>The viewport is not un-set when changes are made to filter or sort, but changes will continue to be streamed in.
* It is suggested that the viewport be changed to the desired position (usually the first N rows) after any filter/sort
* change is made. Likewise, {@link #getViewportData()} will always return the most recent data, and will not wait if a
* new operation is pending.</li>
* <li>Custom columns are not directly supported. If the TreeTable was created client-side, the original Table can have
* custom columns applied, and the TreeTable can be recreated.</li>
* <li>Whereas Table has a {@link JsTable#getTotalsTableConfig()} property, it is defined here as a method,
* {@link #getTotalsTableConfig()}. This returns a promise so the config can be fetched asynchronously.</li>
* <li>Totals Tables for trees vary in behavior between tree tables and roll-up tables. This behavior is based on the
* original flat table used to produce the Tree Table - for a hierarchical table (i.e. Table.treeTable in the query
* config), the totals will include non-leaf nodes (since they are themselves actual rows in the table), but in a
* roll-up table, the totals only include leaf nodes (as non-leaf nodes are generated through grouping the contents of
* the original table). Roll-ups also have the {@link JsRollupConfig#includeConstituents} property, indicating that a
* {@link Column} in the tree may have a {@link Column#getConstituentType()} property reflecting that the type of cells
* where {@link TreeRow#hasChildren()} is false will be different from usual.</li>
* </ul>
*/
@JsType(namespace = "dh", name = "TreeTable")
public class JsTreeTable extends HasLifecycle implements ServerObject {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ public JsRunnable subscribeToFieldUpdates(JsConsumer<JsVariableChanges> callback
};
}

@JsIgnore
@Override
public void notifyServerShutdown(TerminationNotificationResponse success) {
final String details;
Expand Down

0 comments on commit 11537f0

Please sign in to comment.