Module jdk.incubator.adba

Package jdk.incubator.sql2

Interface MultiOperation<T>

Type Parameters:

T - The type of the result of this Operation

All Superinterfaces:

Operation<T>, OutOperation<T>, ParameterizedOperation<T>, PrimitiveOperation<T>

public interface MultiOperation<T>
extends OutOperation<T>

A multi-operation is an Operation that returns one or more results in addition to the out result defined by the Operation. Each result is processed by an Operation. The Operations can be created by calling rowOperation(), or rowCountOperation() if the kind of results is known. These results are processed in the order the Operations are submitted. Any results not processed by an explicit Operation is processed by calling the appropriate handler specified by onRows(java.util.function.BiConsumer<java.lang.Integer, jdk.incubator.sql2.RowOperation<T>>) or onCount(java.util.function.BiConsumer<java.lang.Integer, jdk.incubator.sql2.RowCountOperation<T>>). If any result is an error that error is processed by calling the handler specified by Operation.onError(java.util.function.Consumer<java.lang.Throwable>) of the corresponding Operation. If the appropriate handler is not specified that result is ignored, including errors. ISSUE: Should this have a collector?

Method Summary

Modifier and Type	Method	Description
MultiOperation<T>	apply(java.util.function.Function<Result.OutColumn,? extends T> processor)	Provide a processor that will handle the result of executing the SQL.
MultiOperation<T>	onCount(java.util.function.BiConsumer<java.lang.Integer,RowCountOperation<T>> handler)	Provides a handler for trailing count results.
MultiOperation<T>	onError(java.util.function.BiConsumer<java.lang.Integer,java.lang.Throwable> handler)	Provides an error handler for this Operation.
MultiOperation<T>	onError(java.util.function.Consumer<java.lang.Throwable> handler)	This handler is called if the execution fails completely.
MultiOperation<T>	onRows(java.util.function.BiConsumer<java.lang.Integer,RowOperation<T>> handler)	Provides a handler for trailing row sequence results.
MultiOperation<T>	outParameter(java.lang.String id, SqlType type)	Register an out parameter identified by the given id.
RowCountOperation<T>	rowCountOperation()	Returns a RowCountOperation to process a count result.
RowOperation<T>	rowOperation()	Returns a RowOperation to process a row sequence result.
RowPublisherOperation<T>	rowPublisherOperation()	Returns a RowPublisherOperation to process a row sequence result.
MultiOperation<T>	set(java.lang.String id, java.lang.Object value)	Set a parameter value.
MultiOperation<T>	set(java.lang.String id, java.lang.Object value, SqlType type)	Set a parameter value.
MultiOperation<T>	set(java.lang.String id, java.util.concurrent.CompletionStage<?> source)	Set a parameter value to be the future value of a CompletionStage.
MultiOperation<T>	set(java.lang.String id, java.util.concurrent.CompletionStage<?> source, SqlType type)	Set a parameter value to be the value of a CompletionStage.
MultiOperation<T>	timeout(java.time.Duration minTime)	The minimum time before this Operation might be canceled automatically.

Methods inherited from interface jdk.incubator.sql2.PrimitiveOperation

submit

Method Detail

rowOperation

RowOperation<T> rowOperation()

Returns a RowOperation to process a row sequence result. The Operations are executed in the order they are submitted. If a result is of the wrong type for the next submitted Operation the MultiOperation is completed with IllegalStateException.

Returns:

a RowOperation that is part of this MultiOperation

rowPublisherOperation

RowPublisherOperation<T> rowPublisherOperation()

Returns a RowPublisherOperation to process a row sequence result. The Operations are executed in the order they are submitted. If a result is of the wrong type for the next submitted Operation the MultiOperation is completed with IllegalStateException.

Returns:

a RowPublisherOperation that is part of this MultiOperation

rowCountOperation

RowCountOperation<T> rowCountOperation()

Returns a RowCountOperation to process a count result. The Operations are executed in the order they are submitted. If a result is of the wrong type for the next submitted Operation the MultiOperation is completed with IllegalStateException.

Returns:

a RowCountOperation that is part of this MultiOperation

onCount

MultiOperation<T> onCount(java.util.function.BiConsumer<java.lang.Integer,RowCountOperation<T>> handler)

Provides a handler for trailing count results. The provided handler is called for each count result not processed by RowCountOperation. When called the first argument is the number of results that preceeded the current result. The second argument is a RowCountOperation that will process the current result. This RowCountOperation has not been configured in any way nor has it been submitted. The handler configures the RowCountOperation and submits it. The count result is processed when the RowCountOperation is submitted. If the RowCountOperation is not submitted when the handler returns the count result is ignored. If this method is not called any trailing count results are ignored.

Parameters:

handler - not null

Returns:

this MultiOperation

Throws:

java.lang.IllegalStateException - if this method was called previously

onRows

MultiOperation<T> onRows(java.util.function.BiConsumer<java.lang.Integer,RowOperation<T>> handler)

Provides a handler for trailing row sequence results. The provided handler is called for each row sequence result not processed by a RowOperation. When called the first argument is the number of results that preceeded the current result. The second argument is a RowOperation that will process the current result. This RowOperation has not been configured in any way nor has it been submitted. The handler configures the RowOperation and submits it. The row sequence result is processed when the RowOperation is submitted. If the RowOperation is not submitted when the handler returns, the row sequence result is ignored. If this method is not called any trailing row sequence results are ignored. ISSUE: Should there be a version of this method that provides RowProcessorOperations? If so only one of that method or this one can be called.

Parameters:

handler -

Returns:

This MultiOperation

Throws:

java.lang.IllegalStateException - if this method was called previously

onError

MultiOperation<T> onError(java.util.function.BiConsumer<java.lang.Integer,java.lang.Throwable> handler)

Provides an error handler for this Operation. The provided handler is called for each error that occurs. When called the first argument is the number of results, including errors, that preceeded the current error. The second argument is a Throwable corresponding to the error. When the handler returns processing of the MultiOperation results continues. Only one onError method may be called.

Parameters:

handler - a BiConsumer that handles an error

Returns:

this MultiOperation

Throws:

java.lang.IllegalStateException - if this method or onError(java.util.function.Consumer) was called previously

onError

MultiOperation<T> onError(java.util.function.Consumer<java.lang.Throwable> handler)

This handler is called if the execution fails completely. If the execution returns any individual results, even if any or all of those results are errors, this handler is not called. Provides an error handler for this Operation. If execution of this Operation results in an error, before the Operation is completed, the handler is called with the Throwable as the argument. The type of the Throwable is implementation dependent.

Specified by:

onError in interface Operation<T>

Specified by:

onError in interface OutOperation<T>

Returns:

this MultiOperation

apply

MultiOperation<T> apply(java.util.function.Function<Result.OutColumn,? extends T> processor)

Provide a processor that will handle the result of executing the SQL.

Specified by:

apply in interface OutOperation<T>

Parameters:

processor - the Function that will be called to process the result of this OutOperation

Returns:

this MultiOperation

outParameter

MultiOperation<T> outParameter(java.lang.String id,
                               SqlType type)

Register an out parameter identified by the given id.

Specified by:

outParameter in interface OutOperation<T>

Parameters:

id - the parameter identifier

type - the SQL type of the value of the parameter

Returns:

this MultiOperation

set

MultiOperation<T> set(java.lang.String id,
                      java.lang.Object value,
                      SqlType type)

Set a parameter value. The value is captured and should not be modified before the Operation is completed.

Specified by:

set in interface OutOperation<T>

Specified by:

set in interface ParameterizedOperation<T>

Parameters:

id - the identifier of the parameter marker to be set

value - the value the parameter is to be set to

type - the SQL type of the value to send to the database

Returns:

this MultiOperation

set

MultiOperation<T> set(java.lang.String id,
                      java.lang.Object value)

Set a parameter value. Use a default SQL type determined by the type of the value argument. The value is captured and should not be modified before the Operation is completed.

Specified by:

set in interface OutOperation<T>

Specified by:

set in interface ParameterizedOperation<T>

Parameters:

id - the identifier of the parameter marker to be set

value - the value the parameter is to be set to

Returns:

this MultiOperation

set

MultiOperation<T> set(java.lang.String id,
                      java.util.concurrent.CompletionStage<?> source,
                      SqlType type)

Set a parameter value to be the value of a CompletionStage. The Operation will not be executed until the CompletionStage is completed. This method allows submitting Operations that depend on the result of previous Operations rather than requiring that the dependent Operation be submitted only when the previous Operation completes.

Specified by:

set in interface OutOperation<T>

Specified by:

set in interface ParameterizedOperation<T>

Parameters:

id - the identifier of the parameter marker to be set

source - the CompletionStage that provides the value the parameter is to be set to

type - the SQL type of the value to send to the database

Returns:

this MultiOperation

set

MultiOperation<T> set(java.lang.String id,
                      java.util.concurrent.CompletionStage<?> source)

Set a parameter value to be the future value of a CompletionStage. The Operation will not be executed until the CompletionStage is completed. This method allows submitting Operations that depend on the result of previous Operations rather than requiring that the dependent Operation be submitted only when the previous Operation completes. Use a default SQL type determined by the type of the value of the CompletionStage argument.

Specified by:

set in interface OutOperation<T>

Specified by:

set in interface ParameterizedOperation<T>

Parameters:

id - the identifier of the parameter marker to be set

source - the CompletionStage that provides the value the parameter is to be set to

Returns:

this MultiOperation

timeout

MultiOperation<T> timeout(java.time.Duration minTime)

The minimum time before this 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.

Specified by:

timeout in interface Operation<T>

Specified by:

timeout in interface OutOperation<T>

Parameters:

minTime - minimum time to wait before attempting to cancel

Returns:

this MultiOperation