org.voltdb

Class VoltCompoundProcedure

java.lang.Object

org.voltdb.VoltNonTransactionalProcedure

org.voltdb.VoltCompoundProcedure

public class VoltCompoundProcedure
extends org.voltdb.VoltNonTransactionalProcedure

Base class for any user-provided compound procedures. A compound procedure is one that invokes other procedures, perhaps in order to combine results from those procedures into some table update.

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.

Since:

11.4.0

Nested Class Summary

Nested Classes

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 Summary

Constructors

Constructor and Description
VoltCompoundProcedure()

Method Summary

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.

Methods inherited from class org.voltdb.VoltNonTransactionalProcedure

callAllPartitionProcedure, callProcedure, getClusterId

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VoltCompoundProcedure

public VoltCompoundProcedure()

Method Detail

newStageList

public final 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. 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.

Parameters:

consumer - first stage handler

Returns:

StageListBuilder instance of builder class

See Also:

VoltCompoundProcedure.StageListBuilder

queueProcedureCall

public final void queueProcedureCall(java.lang.String procName,
                                     java.lang.Object... params)

Queues an asynchronous procedure call, to be executed when the current stage returns.

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.

Parameters:

procName - name of procedure to call

params - arguments as required by called procedure

completeProcedure

public final void completeProcedure(long result)

All processing of this compound procedure is now complete. A response will be sent to the client. No more stages will be executed.

If the current stage has queued any procedure calls before calling completeProcedure, those calls will not be issued: execution is complete.

Parameters:

result - the result of the compound procedure

completeProcedure

public final void completeProcedure(VoltTable result)

All processing of this compound procedure is now complete. A response will be sent to the client. No more stages will be executed.

If the current stage has queued any procedure calls before calling completeProcedure, those calls will not be issued: execution is complete.

Parameters:

result - the result of the compound procedure

completeProcedure

public final void completeProcedure(VoltTable[] result)

All processing of this compound procedure is now complete. A response will be sent to the client. No more stages will be executed.

If the current stage has queued any procedure calls before calling completeProcedure, those calls will not be issued: execution is complete.

Parameters:

result - the result of the compound procedure

abortProcedure

public final void abortProcedure(java.lang.String reason)

Indicates that processing of this compound procedure is being abandoned. A response will be sent to the client with status set to 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.

Parameters:

reason - to be included in client response

setAppStatusCode

public void setAppStatusCode(byte status)

Set the application status code that will be returned to the client as part of the ClientResponse. This is distinct from the VoltDB-provided status code. The meaning is determined by your procedure and the application.

Overrides:

setAppStatusCode in class org.voltdb.VoltNonTransactionalProcedure

Parameters:

status - application-specific status code

setAppStatusString

public void setAppStatusString(java.lang.String message)

Set the application status string that will be returned to the client as part of the ClientResponse. This is distinct from the VoltDB-provided status string. The meaning is determined by your procedure and the application.

Overrides:

setAppStatusString in class org.voltdb.VoltNonTransactionalProcedure

Parameters:

message - application-specific status string