Package 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

  • Constructor Details

    • VoltCompoundProcedure

      public VoltCompoundProcedure()

  • Method Details

    • newStageList

      public final VoltCompoundProcedure.StageListBuilder newStageList(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:

    • queueProcedureCall

      public final void queueProcedureCall(String procName, 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(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(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