public class VoltCompoundProcedure
extends org.voltdb.VoltNonTransactionalProcedure
It is important to understand that a compound procedure does not provide transactional guarantees. If there is a failure during execution, in-progress transactions executed by the compound proc may be rolled back as usual, but completed transactions will not be.
Operation of a compound procedure is essentially asynchronous. In a typical pattern, calls are issued to other procedures, and the results of those calls are processed as they arrive. To facilitate this, the execution of the compound procedure is separated into 'stages'. A stage issues one or more procedure calls, and then exits. The next stage will be executed with the responses from the calls issued by the previous stage. Intermediate results and working values must be saved in member variables.
The last stage must complete the compound procedure, and return
a result, by calling completeProcedure
. The result
must be one of the following types
Long
VoltTable
VoltTable[]
The compound procedure starts its execution in its run(...)
method, which must accept parameters compatible with the parameters provided
by the client. The run
method must set up a list of
execution stages; the auxiliary class StageListBuilder
is provided to help with this. Any return value from run
is ignored, but must have a type acceptable to the Volt compiler.
The primitive type 'long' is recommended.
Execution of the compound procedure can be terminated prematurely
by calling abortProcedure
or, equivalently, by throwing
a CompoundProcAbortException
. This will be reported
to the client via the usual ClientResponse
with
a status of COMPOUND_PROC_USER_ABORT
.
Modifier and Type | Class and Description |
---|---|
static class |
VoltCompoundProcedure.CompoundProcAbortException
Thrown from a stored procedure to abort a VoltCompoundProcedure.
|
static class |
VoltCompoundProcedure.Stage
Represents the stages of processing of a
VoltCompoundProcedure . |
class |
VoltCompoundProcedure.StageListBuilder
Builds a list of execution stages for this
VoltCompoundProcedure . |
Constructor and Description |
---|
VoltCompoundProcedure() |
Modifier and Type | Method and Description |
---|---|
void |
abortProcedure(java.lang.String reason)
Indicates that processing of this compound procedure
is being abandoned.
|
void |
completeProcedure(long result)
All processing of this compound procedure is now complete.
|
void |
completeProcedure(VoltTable result)
All processing of this compound procedure is now complete.
|
void |
completeProcedure(VoltTable[] result)
All processing of this compound procedure is now complete.
|
VoltCompoundProcedure.StageListBuilder |
newStageList(java.util.function.Consumer<org.voltdb.client.ClientResponse[]> consumer)
Returns a
VoltCompoundProcedure.StageListBuilder for use in building
the list of execution stages for this compound
procedure. |
void |
queueProcedureCall(java.lang.String procName,
java.lang.Object... params)
Queues an asynchronous procedure call, to be executed
when the current stage returns.
|
void |
setAppStatusCode(byte status)
Set the application status code that will be returned to the
client as part of the
ClientResponse . |
void |
setAppStatusString(java.lang.String message)
Set the application status string that will be returned to the
client as part of the
ClientResponse . |
public final VoltCompoundProcedure.StageListBuilder newStageList(java.util.function.Consumer<org.voltdb.client.ClientResponse[]> consumer)
VoltCompoundProcedure.StageListBuilder
for use in building
the list of execution stages for this compound
procedure. The initial stage is given as an argument;
other stages can be added according to the needs of
the application.
Usage:
newStageList(STAGE)
.then(STAGE)
.then(STAGE)
.build();
The stage list must be built during execution of
your procedure's run
method.consumer
- first stage handlerVoltCompoundProcedure.StageListBuilder
public final void queueProcedureCall(java.lang.String procName, java.lang.Object... params)
The system supports parallel initiation. You can code
several calls to queueProcedureCall
in
a single stage. There is a system limit on the number
of calls that can be queued in any one stage; this
limit defaults to 10, but can be changed in the VoltDB
deployment file.
When all calls have completed, the next stage will be
entered, with the results of all calls. The results
will have the same order as calls issued to
queueProcedureCall
.
queueProcedureCall
must only be called
in the context of a thread that is executing either
the initial run
call, or one of the
stages set up for the procedure.
procName
- name of procedure to callparams
- arguments as required by called procedurepublic final void completeProcedure(long result)
If the current stage has queued any procedure calls
before calling completeProcedure
, those
calls will not be issued: execution is complete.
result
- the result of the compound procedurepublic final void completeProcedure(VoltTable result)
If the current stage has queued any procedure calls
before calling completeProcedure
, those
calls will not be issued: execution is complete.
result
- the result of the compound procedurepublic final void completeProcedure(VoltTable[] result)
If the current stage has queued any procedure calls
before calling completeProcedure
, those
calls will not be issued: execution is complete.
result
- the result of the compound procedurepublic final void abortProcedure(java.lang.String reason)
COMPOUND_PROC_USER_ABORT
.
Completed calls previously issued by the compound procedure will not be affected; there is no rollback of transactions.
This should be the last action taken by the compound procedure.
If the current stage has queued any procedure calls
before calling abortProcedure
, those
calls will not be issued: execution has concluded.
Throwing a CompoundProcAbortException
can be
used instead of calling abortProcedure
, with
the same effect.
reason
- to be included in client responsepublic void setAppStatusCode(byte status)
ClientResponse
. This is
distinct from the VoltDB-provided status code. The meaning
is determined by your procedure and the application.setAppStatusCode
in class org.voltdb.VoltNonTransactionalProcedure
status
- application-specific status codepublic void setAppStatusString(java.lang.String message)
ClientResponse
. This is
distinct from the VoltDB-provided status string. The meaning
is determined by your procedure and the application.setAppStatusString
in class org.voltdb.VoltNonTransactionalProcedure
message
- application-specific status string