Interface JsPendingTable<T>

Type Parameters:
T - the type of table awaiting this resolves to. Use resolve(Object) to get JsResolvedTable.
All Superinterfaces:
JsTableOperations, PromiseLike<T>, ServerObject

@TsName(namespace="dh", name="PendingTable") @TsInterface public interface JsPendingTable<@TsDefault(JsResolvedTable.class) T> extends JsTableOperations, PromiseLike<T>
A table being created on the server, on which more operations can be chained before it exists. Supports all the methods of JsTableOperations, each of which returns another pending table.

A pending table is a thenable: it can be awaited, or given callbacks with then, and resolves to a table whose data can be read. What it resolves to depends on where it came from:

On the other hand, resolve(Object) always gives a JsResolvedTable. Either await or resolve a pending table, but not both. Repeated usage of either yields the same instance.

A pending table has no catch or finally. For those, wrap it with Promise.resolve(...) in the task that created it.

A pending table has no owner. Whoever awaits or resolves it must close the resulting table, so the server can free its resources. JsTableOperations describes who owns what.

A pending table is only valid in the task that created it. Any use after the task is incorrect and will reject if detected: it cannot be awaited, resolved, have then()-invoked or otherwise used as a promise, passed as an argument to another operation, or have operations called on it. The one exception is cancel(), which can be called at any time, and only serves to stop pending work.

When dealing with multiple pending tables, either individually use Promise.resolve or resolve(Object) and await those promises, or use DhNamespace.resolveAll(ReadonlyArray, Object) to automatically await their successes, and clean them all up if any one fails.

  • Method Details

    • cancel

      @JsMethod void cancel()
      Abandons this table: stops the work if it is not done, and closes the table if it was already delivered. Use it when the result is no longer wanted, such as when a newer request replaces it.
      • Not yet delivered: a request not yet sent is never sent, and the server should cancel work it has not started or stop work it has started. Promises on the canceled table reject with "Operation canceled", downstream operations will instead reject indicating that a source failed.
      • Already delivered: the table it produced is closed, as close() on it would. Copies made of the delivered table will stay open (e.g. JsResolvedTable.copy() and JsResolvedTable.createMutableTable()).
      • Tables chained on this pending table also fail - those still being made, and those chained afterward, which are never sent.
      A call outside the batch that already named this table, such as InputTable.addTable, IdeConnection.shareObject, IdeSession.shareObject or IdeSession.bindTableToVariable, cannot be withdrawn once sent. If it has not finished, its promise rejects, but the server may still complete it. A call that has finished is unaffected.

      This is the only method on PendingTable that can be successfully called after the task that created it has finished.

      See also resolve(Object) on how to use an AbortSignal to cancel pending operations. When designing a user interface that cancels operations, keep in mind that it is not always possible to cancel work on the server, and it may make sense to also debounce operations.

      Canceling the JsTable.operations() of a JsTable leaves the JsTable and its server-side tables as they are.

    • resolve

      @JsMethod elemental2.promise.Promise<JsResolvedTable> resolve(@JsOptional @TsTypeRef(ResolveOptions.class) @JsNullable @TsTypeRef(ResolveOptions.class) Object options)
      The table this pending table produces, as a JsResolvedTable whose data can be read and on which more operations can be chained, whatever awaiting it gives. This holds for the JsTable.operations() of a JsTable too. Repeated calls give the same promise and the same table. Resolving does not change who owns the table. Use JsResolvedTable.copy() for an instance with its own lifetime. A pending table that was canceled, or is resolved after the task that created it, rejects instead, as does a fetched one that was already awaited.
      Parameters:
      options - optionally, a signal that cancels this pending table when aborted
      Returns:
      a promise of the resolved table
    • resolve

      @JsIgnore default elemental2.promise.Promise<JsResolvedTable> resolve()
      As resolve(Object) with no options.