S
- The type of the result of the member Operation
sT
- The type of the collected results the member
Operation
sOperation<T>
Connection
public interface OperationGroup<S,T> extends Operation<T>
Operation
s that share certain properties, are managed as a
unit, and are executed as a unit. The Operation
s created by an
OperationGroup
and submitted are the member Operation
s of
that OperationGroup
.
An OperationGroup
conceptually has a collection of member
Operation
s. When an OperationGroup
is submitted it is placed
in the collection of the OperationGroup
of which it is a member. The
member OperationGroup
is executed according to the attributes of the
OperationGroup
of which it is a member. The member Operation
s
of an OperationGroup
are executed according to the attributes of that
OperationGroup
.
How an OperationGroup
is executed depends on its attributes.
If an OperationGroup
has a condition and the value of that condition
is Boolean.TRUE
then execute the member Operation
s as below.
If it is Boolean.FALSE
then the OperationGroup
is completed
with the value null. If the condition completed exceptionally then the
OperationGroup
is completed exceptionally with a
SqlSkippedException
that has that exception as its cause.
If the OperationGroup
is sequential the member Operation
s are
executed in the order they were submitted. If it is parallel, they may be
executed in any order including simultaneously.
If an OperationGroup
is dependent and a member Operation
completes exceptionally the remaining member Operation
s in the
collection are completed exceptionally with a SqlSkippedException
that has the initial Exception
as its cause. A member
Operation
in-flight may either complete normally or be completed
exceptionally but must complete one way or the other. [NOTE: Too strong?]
If an OperationGroup
is held additional member Operation
s may
be submitted after the OperationGroup
is submitted. If an
OperationGroup
is not held, no additional member Operation
s
may be submitted after the OperationGroup
is submitted. If an
OperationGroup
is held it will be completed only after it is released
or if conditional and the condition is not Boolean.TRUE
. If a
OperationGroup
is dependent, held, one of its member
Operation
s completed exceptionally, and its queue is empty then the
OperationGroup
is released.
ISSUE: Currently no way to create a nested OperationGroup
. That is a
intentional limitation but may be a simplification we can live with. Or not.Modifier and Type | Method | Description |
---|---|---|
<R extends S> |
arrayCountOperation(java.lang.String sql) |
Return a new
ArrayCountOperation . |
<A,S extends T> |
collect(java.util.stream.Collector<? super Result.Row,A,S> c) |
Provides a
Collector to reduce the results of the member
Operation s.The result of this OperationGroup is the result
of calling finisher on the final accumulated result. |
default OperationGroup<S,T> |
commitMaybeRollback(Transaction trans) |
Convenience method that creates and submits a endTransaction
Operation
that commits by default but can be set to rollback by calling
Transaction.setRollbackOnly() . |
OperationGroup<S,T> |
conditional(java.util.concurrent.CompletionStage<java.lang.Boolean> condition) |
Define a condition that determines whether the member
Operation s of
this OperationGroup are executed or not. |
<R extends S> |
countOperation(java.lang.String sql) |
Return a new
CountOperation . |
<R extends S> |
dynamicMultiOperation(java.lang.String sql) |
Return a
DynamicMultiOperation . |
Operation<TransactionOutcome> |
endTransactionOperation(Transaction trans) |
Return an
Operation that ends the database transaction. |
OperationGroup<S,T> |
holdForMoreMembers() |
Mark this
OperationGroup as held. |
OperationGroup<S,T> |
independent() |
Mark this
OperationGroup as independent. |
LocalOperation<T> |
localOperation() |
Return a
LocalOperation . |
OperationGroup<S,T> |
logger(java.util.logging.Logger logger) |
Supply a
Logger for the implementation of this
OperationGroup to use to log significant events. |
Operation<java.lang.Void> |
operation(java.lang.String sql) |
Return a new
Operation for a SQL that doesn't return any result,
for example DDL. |
java.util.concurrent.Flow.Processor<Operation<T>,Submission<T>> |
operationProcessor() |
Returns a Flow.Processor that subscribes to a sequence of Operations and
produces a sequence of corresponding Submissions.
|
<R extends S> |
outOperation(java.lang.String sql) |
Return a new
OutOperation . |
OperationGroup<S,T> |
parallel() |
Mark this
OperationGroup as parallel. |
OperationGroup<S,T> |
releaseProhibitingMoreMembers() |
Allow this
OperationGroup to be completed and removed from the
queue once all of its member Operation s have been completed. |
<R extends S> |
rowOperation(java.lang.String sql) |
Return a
ParameterizedRowOperation . |
<R extends S> |
staticMultiOperation(java.lang.String sql) |
Return a
StaticMultiOperation . |
OperationGroup<S,T> |
timeout(java.time.Duration minTime) |
The minimum time before this
Operation might be canceled
automatically. |
OperationGroup<S,T> parallel()
OperationGroup
as parallel. If this method is not called
the OperationGroup
is sequential. If an OperationGroup
is
parallel, member Operation
s may be executed in any order including
in parallel. If an OperationGroup
is sequential, the default,
member Operation
s are executed strictly in the order they are
submitted.
Note: There is no covariant override of this method in Connection
as there is only a small likelihood of needing it.OperationGroup
java.lang.IllegalStateException
- if this method has been submitted or any
member Operation
s have been created.OperationGroup<S,T> independent()
OperationGroup
as independent. If this method is not
called the OperationGroup
is dependent, the default. If an
OperationGroup
is independent then failure of one member
Operation
does not affect the execution of other member
Operation
s. If an OperationGroup
is dependent then failure
of one member Operation
will cause all member Operation
s
remaining in the queue to be completed exceptionally with a
SqlSkippedException
with the cause set to the original exception.
Note: There is no covariant override of this method in Connection
as there is only a small likelihood of needing it.OperationGroup
java.lang.IllegalStateException
- if this OperationGroup
has been
submitted or any member Operation
s have been createdOperationGroup<S,T> conditional(java.util.concurrent.CompletionStage<java.lang.Boolean> condition)
Operation
s of
this OperationGroup
are executed or not. If and when this
OperationGroup
is executed then if the condition argument is
completed with Boolean.TRUE
the member Operation
s are
executed. If Boolean.FALSE
or if it is completed exceptionally the
member Operation
s are not executed but are removed from the queue.
After all member Operation
s have been removed from the queue this
OperationGroup
is completed with null
.
Note: There is no covariant override of this method in Connection as there
is only a small likelihood of needing it.
ISSUE: Should the member Operations be skipped or otherwise completed
exceptionally?condition
- a CompletionStage
the value of which determines whether
this OperationGroup
is executed or notjava.lang.IllegalStateException
- if this OperationGroup
has been
submitted or any member Operation
s have been createdOperationGroup<S,T> holdForMoreMembers()
OperationGroup
as held. It can be executed but cannot be
completed. A OperationGroup
that is held remains in the queue even
if all of its current member Operation
s have completed. So long as
the OperationGroup
is held new member Operation
s can be
submitted. A OperationGroup
that is held must be released before it
can be completed and removed from the queue.
Note: There is no covariant override of this method in Connection as there
is only a small likelihood of needing it.
ISSUE: Need a better name.java.lang.IllegalStateException
- if this OperationGroup
has been
submittedOperationGroup<S,T> releaseProhibitingMoreMembers()
OperationGroup
to be completed and removed from the
queue once all of its member Operation
s have been completed. After
this method is called no additional member Operation
s can be
submitted. Once all member Operation
s have been removed from the
queue this OperationGroup
will be completed and removed from the
queue.
Calling this method when this OperationGroup
is not held is a noop.
Note: There is no covariant override of this method in Connection as there
is only a small likelihood of needing it.
ISSUE: Need a better name.java.lang.IllegalStateException
- if this OperationGroup
has been
completed<A,S extends T> RowOperation<T> collect(java.util.stream.Collector<? super Result.Row,A,S> c)
Collector
to reduce the results of the member
Operation
s.The result of this OperationGroup
is the result
of calling finisher on the final accumulated result. If the
Collector
is Collector.Characteristics.UNORDERED
the member
Operation
results may be accumulated out of order. If the
Collector
is Collector.Characteristics.CONCURRENT
then the
member Operation
results may be split into subsets that are reduced
separately and then combined. If this OperationGroup
is sequential,
the characteristics of the Collector
only affect how the results of
the member Operation
s are collected; the member Operation
s
are executed sequentially regardless. If this OperationGroup
is
parallel the characteristics of the Collector
may influence the
execution order of the member Operation
s.A
- the type of the accumulatorS
- the type of the final resultc
- the Collector. Not null.java.lang.IllegalStateException
- if called more than once or if this
OperationGroup
has been submitted<R extends S> ArrayCountOperation<R> arrayCountOperation(java.lang.String sql)
ArrayCountOperation
.
Usage Note: Frequently use of this method will require a type witness to enable correct type inferencing.
conn.<List<Integer>>arrayCountOperation(sql)
.set ...
.collect ...
.submit ...
R
- the result type of the returned ArrayCountOperation
sql
- SQL to be executed. Must return an update count.ArrayCountOperation
that is a member of this
OperationGroup
<R extends S> ParameterizedCountOperation<R> countOperation(java.lang.String sql)
CountOperation
.R
- the result type of the returned CountOperation
sql
- SQL to be executed. Must return an update count.CountOperation
that is a member of this
OperationGroup
Operation<java.lang.Void> operation(java.lang.String sql)
Operation
for a SQL that doesn't return any result,
for example DDL.sql
- SQL for the Operation
.Operation
that is a member of this
OperationGroup
<R extends S> OutOperation<R> outOperation(java.lang.String sql)
OutOperation
. The SQL must return a set of zero or
more out parameters or function results.R
- the result type of the returned OutOperation
sql
- SQL for the Operation
. Must return zero or more out
parameters or function results.OutOperation
that is a member of this
OperationGroup
<R extends S> ParameterizedRowOperation<R> rowOperation(java.lang.String sql)
ParameterizedRowOperation
.R
- the type of the result of the returned ParameterizedRowOperation
sql
- SQL for the Operation
. Must return a row sequence.ParameterizedRowOperation
that is a member of this
OperationGroup
<R extends S> StaticMultiOperation<R> staticMultiOperation(java.lang.String sql)
StaticMultiOperation
.R
- the type of the result of the returned
StaticMultiOperation
sql
- SQL for the Operation
StaticMultiOperation
that is a member of this
OperationGroup
<R extends S> DynamicMultiOperation<R> dynamicMultiOperation(java.lang.String sql)
DynamicMultiOperation
. Use this when the number and type
of the results is not knowable.R
- the type of the result of the returned
DynamicMultiOperation
sql
- SQL for the Operation
DynamicMultiOperation
that is a member of this
OperationGroup
Operation<TransactionOutcome> endTransactionOperation(Transaction trans)
Operation
that ends the database transaction.
The transaction is ended with a commit unless the Transaction
has
been Transaction.setRollbackOnly()
in which
case the transaction is ended with a rollback.
The type argument OperationGroup
of the containing OperationGroup
must be
a supertype of TransactionOutcome
.trans
- the Transaction that determines whether the Operation does a
database commit or a database rollback.Operation
that will end the database transaction.java.lang.IllegalStateException
- if this OperationGroup
has been submitted and
is not held or is parallel.default OperationGroup<S,T> commitMaybeRollback(Transaction trans)
Operation
that commits by default but can be set to rollback by calling
Transaction.setRollbackOnly()
.trans
- the Transaction that determines whether the Operation is a
database commit or a database rollback.OperationGroup
java.lang.IllegalStateException
- if this OperationGroup
has been submitted and
is not held or is parallel.LocalOperation<T> localOperation()
LocalOperation
.java.lang.IllegalStateException
- if this OperationGroup has been submitted and
is not heldjava.util.concurrent.Flow.Processor<Operation<T>,Submission<T>> operationProcessor()
java.lang.IllegalStateException
- if there is an active ProcessorOperationGroup<S,T> logger(java.util.logging.Logger logger)
Logger
for the implementation of this
OperationGroup
to use to log significant events. Exactly what
events are logged, at what Level the events are logged and with what
parameters is implementation dependent. All member Operation
s of
this OperationGroup
will use the same Logger
except a
member OperationGroup
that is supplied with a different
Logger
uses that Logger
.
Supplying a Logger
configured with a
MemoryHandler
with the
MemoryHandler.pushLevel
set to
Level.WARNING
will result in no log output in
normal operation. In the event of an error the actions leading up to the
error will be logged.
Implementation Note: Implementations are encouraged to log the creation of
this OperationGroup
set to Level.INFO
, the
creation of member Operation
s at the
Level.CONFIG
level, and execution of member
Operation
s at the Level.FINE
level.
Detailed information about the execution of member Operation
s may
be logged at the Level.FINER
and
Level.FINEST
levels. Errors in the execution of
user code should be logged at the Level.WARNING
Level. Errors in the implementation code should be logged at the
Level.SEVERE
Level.logger
- used by the implementation to log significant eventsOperationGroup
OperationGroup<S,T> timeout(java.time.Duration minTime)
Operation
Operation
might be canceled
automatically. The default value is forever. The time is
counted from the beginning of Operation execution. The Operation will not
be canceled before minTime
after the beginning of execution.
Some time at least minTime
after the beginning of execution,
an attempt will be made to cancel the Operation
if it has not yet
completed. Implementations are encouraged to attempt to cancel within a
reasonable time, though what is reasonable is implementation dependent.Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2017, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.
DRAFT JDBC 4.4 EA