jdk-sandbox: comparison src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/package-info.java

equal deleted inserted replaced

-:6ba0dbf6a75f
+:62e92191354d
 * remaining not-yet-executed members are completed exceptionally. If the
 * {@link OperationGroup} is independent, the member {@link Operation}s are
 * executed regardless of whether one or more fails.</p>
 *
 * <p>
-* A {@link Connection} is itself an {@link OperationGroup} and so can be
+* A single context in a data source is represented by a {@link Session}. A
+* {@link Session} is somewhat analogous to a logical {@link java.sql.Connection}.
+* A physical {@link java.sql.Connection} has no representation in this API; if
+* such an entity exists at all it is strictly internal to an implementation.
+* Within this spec this entity is referred to as a "data source resource".
+* </p>
+*
+* <p>
+* A {@link Session} is itself an {@link OperationGroup} and so can be
 * conditional, parallel, or independent, but by default is unconditional,
-* sequential, dependent. While a {@link Connection} may be created with values
+* sequential, dependent. While a {@link Session} may be created with values
 * other than the defaults, using the defaults is by far the most common case.
 * The API provides convenience methods that support this case. Using these
 * convenience methods is recommended in all but the most unusual circumstances.
-* In particular making the {@link Connection} parallel introduces some
+* In particular making the {@link Session} parallel introduces some
 * challenges that would require a full understanding of the details of the API.
 * It would almost certainly be better to create a parallel
-* {@link OperationGroup} within the {@link Connection}.</p>
+* {@link OperationGroup} within the {@link Session}.</p>
 *
 * <p>
 * <i>
-* ISSUE: Should we disallow {@code Connection.parallel()}?</i></p>
+* ISSUE: Should we disallow {@code Session.parallel()}?</i></p>
 *
 * <p>
 * The {@code java.sql} API frequently provides many ways to do the same thing.
 * This API makes no attempt to do this. For those capabilities this API
 * supports, it frequently defines exactly one way to do something. Doing things
 * better that a feature be unsupported as opposed to users investing substantial
 * effort in an app using that feature only to discover in production that the
 * performance is unacceptable. For example, if an implementation can only support
 * {@link Operation#timeout} through active polling it would be better for that
 * implementation to throw  {@link UnsupportedOperationException} if
-* {@link Operation#timeout} is called.</p>
+* {@link Operation#timeout} is called. To this end every type and method is
+* optional except returning a {@link DataSourceFactory} in response to a call to
+* {@link DataSourceFactory#newFactory} with the appropriate name.</p>
 *
 * <h3>Execution Model</h3>
 *
 * <p>
 * <i>This section describes the function of a conforming implementation. It is
 *
 * <p>
 * An {@link Operation} is executed by causing the action to be performed,
 * processing the result of the action if there is a result processor, and
 * completing the {@link java.util.concurrent.CompletionStage} with the result
-* of the result processor if there is one or with the result of the action if
+* of the result processor if there is one. If the action or the result processing
-* there is no result processor. If the action or the result processing causes
+* causes an unhandled error the {@link java.util.concurrent.CompletionStage} is
-* an unhandled error the {@link java.util.concurrent.CompletionStage} is
 * completed exceptionally. The {@link java.util.concurrent.CompletionStage} is
 * completed asynchronously, as though it were created by calling an
 * <i>async</i> method on {@link java.util.concurrent.CompletionStage}.
 * </p>
 *
 * <p>
 * Performing the action may require one or more interactions with the database.
 * These interactions may be carried out in parallel with processing the result.
-* If the database result is ordered, that result is processed in that order.
+* If the database result is ordered, that result is processed in the order
-*
+* specified by the database.</p>
-* <p>
+*
-* An {@link OperationGroup} has a collection of {@link Operation}s and
+* <p>
+* An {@link OperationGroup} has a collection of member {@link Operation}s and
 * optionally a condition. For a sequential {@link OperationGroup}
 * {@link Operation}s are selected from the collection in the order they were
 * submitted. For a parallel {@link OperationGroup} {@link Operation}s are
 * selected from the collection in any order.</p>
 *
 * it may be completed exceptionally. The {@link OperationGroup} is dependent it
 * is completed exceptionally with the {@link Throwable} that caused the
 * {@link Operation} to complete exceptionally.
 *
 * <p>
-* Note: the {@link Operation}s returned by {@link Connection#closeOperation}
+* Note: the {@link Operation}s returned by {@link Session#closeOperation}
 * and {@link OperationGroup#catchOperation} are never skipped, i.e. never
 * completed exceptionally with {@link SqlSkippedException}. The {@link Operation}
 * returned by {@link OperationGroup#catchOperation} never completes
 * exceptionally so the following {@link Operation} is always executed normally.
 * No {@link Operation} can be submitted after the {@link Operation} returned by
-* {@link Connection#closeOperation} has been submitted.</p> </li>
+* {@link Session#closeOperation} has been submitted.</p> </li>
 * <li>
 * If the {@link OperationGroup} is independent and an {@link Operation}
 * completes exceptionally all other {@link Operation}s are executed regardless.
 * There is no result to be processed for an {@link Operation} that completed
 * exceptionally. The {@link OperationGroup} is not completed exceptionally as
 * the result of one or more {@link Operation}s completing exceptionally.</li>
 * </ul>
 *
 * <p>
-* A {@link Connection} is a distinguished {@link OperationGroup}. A
+* A {@link Session} is a distinguished {@link OperationGroup}. A
-* {@link Connection} is executed upon being submitted.</p>
+* {@link Session} is executed upon being submitted.</p>
 *
 * <h3>Transactions</h3>
 *
 * <p>
 * <i>This section describes the function of a conforming implementation. It is
 * implementation in unexpected ways.</p>
 *
 * <p>
 * The creation of Operations and the subsequent execution of those Operations
 * are separated in time. It is quite reasonable to determine that a transaction
-* should commit after the Operation that ends the transaction is submitted.
+* should commit after the Operation that ends the transaction is submitted. But
-* But if the execution of the transaction does not result in the expected results
+* if the execution of the transaction does not result in the expected results
 * it might be necessary to rollback the transaction rather than commit it. This
 * determination depends on the execution of the Operations long after the
-* endTransaction Operation is created. To address this mismatch, the endTransaction Operation
+* endTransaction Operation is submitted. To address this mismatch, the
-* specified by this API is conditioned by a {@link Transaction}. By default, a
+* endTransaction Operation is conditioned by a {@link TransactionEnd}. By
-* {@link Transaction} will cause an endTransaciton {@link Operation} to commit
+* default, a {@link TransactionEnd} will cause an endTransaciton
-* the transaction. At any time before the endTransaction {@link Operation} that
+* {@link Operation} to commit the transaction. At any time before the
-* references it is executed a {@link Transaction} can be set
+* endTransaction {@link Operation} that references it is executed a
-* to rollback the transaction .</p>
+* {@link TransactionEnd} can be set to rollback the transaction .</p>
 *
 * <p>
-* An endTransaction {@link Operation}, like all {@link Operation}s, is immutable once submitted.
+* An endTransaction {@link Operation}, like all {@link Operation}s, is
-* But an endTransaction {@link Operation} is created with a {@link Transaction} and that
+* immutable once submitted. But an endTransaction {@link Operation} is created
-* {@link Transaction} can be set to commit or rollback. A {@link Transaction} controls the
+* with a {@link TransactionEnd} and that {@link TransactionEnd} can be set to
-* endTransaction {@link Operation} created with it. Using this mechanism an
+* commit or rollback. A {@link TransactionEnd} controls the endTransaction
-* error handler, result handler or other code can cause a subsequent endTransaction
+* {@link Operation} created with it. Using this mechanism an error handler,
+* result handler or other code can cause a subsequent endTransaction
 * {@link Operation} to rollback instead of the default which is to commit.</p>
 *
 * <pre>
 * {@code
-*   Transaction t = conn.getTransaction();
+*   TransactionEnd t = session.getTransactionEnd();
-*   conn.countOperation(updateSql)
+*   session.countOperation(updateSql)
 *       .resultProcessor( count -> {
 *           if (count > 1) t.setRollbackOnly();
 *           return null;
 *       } )
 *       .submit();
-*   conn.catchErrors();
+*   session.catchErrors();
-*   conn.commitMaybeRollback(t);
+*   session.commitMaybeRollback(t);
 * }
 * </pre>
 *
 * <p>
 * In this example if the update SQL modifies more than one row the result
-* processor will set the Transaction to rollback only. When the endTransaction
+* processor will set the {@link TransactionEnd} to rollback only. When the
-* Operation submitted by commitMaybeRollback is executed it will cause
+* endTransaction {@link Operation} submitted by
-* the transaction to rollback.</p>
+* {@link OperationGroup#commitMaybeRollback} is executed it will cause the
-*
+* transaction to rollback.</p>
+*
 *
 * <h3>Implementation Note</h3>
 *
 * <p>
 * If an implementation exposes any implementation specific types and methods, the
 *
 * <p>
 * Consider an implementation that adds a method foo() to RowCountOperation. To do
 * that it would have to expose a type FooRowCountOperation extends RowCountOperation.
 * So that an application can transparently access foo, the implementation would
-* also have to expose FooDataSource, FooOperationGroup and FooConnection. Further
+* also have to expose FooDataSource, FooOperationGroup and FooSession. Further
 * each of these types would have to declare covariant overrides for every method
 * that returns a direct super-type of one of these types.</p>
 * <ul>
 * <li>FooDataSourceFactory must override builder to return FooDataSource.Builder</li>
 * <li>FooDataSource.Builder must override url, password, etc to return a
 * FooDataSource.Builder. build must return a FooDataSource.</li>
-* <li>FooDataSource must override builder to return FooConnection.Builder</li>
+* <li>FooDataSource must override builder to return FooSession.Builder</li>
-* <li>FooConnection.Builder must override url, password, etc to return a
+* <li>FooSession.Builder must override url, password, etc to return a
-* FooConnection.Builder. build must return a FooConnection</li>
+* FooSession.Builder. build must return a FooSession</li>
-* <li>FooDataSource must override getConnection to return FooConnection</li>
+* <li>FooDataSource must override getSession to return FooSession</li>
-* <li>FooConnection must extend FooOperationGroup</li>
+* <li>FooSession must extend FooOperationGroup</li>
 * <li>FooOperationGroup> must override rowCountOperation to return FooRowCountOperation</li>
 * <li>FooRowCountOperation must override apply and onError to return FooRowCountOperation</li>
 * </ul>
 * <p>
 * The intent is to transparently expose the vendor extension without use of casts.
 * {@code
 *   FooDataSourceFactory factory = DataSourceFatory.newFactory("com.foo.FooDataSourceFatory");
 *   FooDataSource dataSource = factory.builder()
 *       .url("scott/tiger@host:port")
 *       .build();
-*   FooConnection conn = dataSource.getConnection();
+*   FooSession session = dataSource.getSession();
-*   CompletionStage<Long> count = conn.rowOperation(sql)
+*   CompletionStage<Long> count = session.rowOperation(sql)
 *       .set("param", value, AdbaType.VARCHAR)
 *       .foo()
 *       .submit()
 *       .getCompletionStage();
 * }

branch	JDK-8188051-branch
changeset 56824	62e92191354d
parent 56797	fb523d4d9185
child 56828	64304e37e9b1