Package org.voltdb

Class VoltProcedure

java.lang.Object
org.voltdb.VoltProcedure
public abstract class VoltProcedure extends Object
Wraps the stored procedure object created by the user with metadata available at runtime. This is used to call the procedure. VoltProcedure is extended by all running stored procedures. Consider this when specifying access privileges.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    VoltProcedure.VoltAbortException
    Thrown from a stored procedure to indicate to VoltDB that the procedure should be aborted and rolled back.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final org.voltdb.Expectation
    EXPECT_EMPTY
    Expect an empty result set (0 rows)
    static final org.voltdb.Expectation
    EXPECT_NON_EMPTY
    Expect a result set with one or more rows
    static final org.voltdb.Expectation
    EXPECT_ONE_ROW
    Expect a result set with exactly one row
    static final org.voltdb.Expectation
    EXPECT_SCALAR
    Expect a result set with a single row and a single column (scalar value)
    static final org.voltdb.Expectation
    EXPECT_SCALAR_LONG
    Expect a result with a single row and a single BIGINT column
    static final org.voltdb.Expectation
    EXPECT_ZERO_OR_ONE_ROW
    Expect a result set with one or no rows

  • Constructor Summary

    Constructors
    Constructor
    Description
    VoltProcedure()
    End users should not instantiate VoltProcedure instances.

  • Method Summary

    Modifier and Type
    Method
    Description
    static final org.voltdb.Expectation
    EXPECT_SCALAR_MATCH(long scalar)
    Expect a result with a single row and a single BIGINT column containing the specified value.
    int
    getClusterId()
    Get the ID of cluster that the client connects to.
    int
    getPartitionId()
     
    Random
    getSeededRandomNumberGenerator()
    Get a Java RNG seeded with the current transaction id.
    long
    getTransactionId()
     
    Date
    getTransactionTime()
    YOU MUST BE RUNNING NTP AND START NTP WITH THE -x OPTION TO GET GOOD BEHAVIOR FROM THIS METHOD - e.g.
    long
    getUniqueId()
    Allow VoltProcedures access to a unique ID generated for each transaction.
    void
    setAppStatusCode(byte statusCode)
    Set the status code that will be returned to the client.
    void
    setAppStatusString(String statusString)
    Set the string that will be turned to the client.
    VoltTable[]
    voltExecuteSQL()
    Execute the currently queued SQL statements and return the result tables.
    VoltTable[]
    voltExecuteSQL(boolean isFinalSQL)
    Execute the currently queued SQL statements and return the result tables.
    void
    voltQueueSQL(SQLStmt stmt, Object... args)
    Queue the SQL statement for execution with the specified argument list.
    void
    voltQueueSQL(SQLStmt stmt, org.voltdb.Expectation expectation, Object... args)
    Queue the SQL statement for execution with the specified argument list, and an Expectation describing the expected results.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • EXPECT_EMPTY

      public static final org.voltdb.Expectation EXPECT_EMPTY
      Expect an empty result set (0 rows)

    • EXPECT_ONE_ROW

      public static final org.voltdb.Expectation EXPECT_ONE_ROW
      Expect a result set with exactly one row

    • EXPECT_ZERO_OR_ONE_ROW

      public static final org.voltdb.Expectation EXPECT_ZERO_OR_ONE_ROW
      Expect a result set with one or no rows

    • EXPECT_NON_EMPTY

      public static final org.voltdb.Expectation EXPECT_NON_EMPTY
      Expect a result set with one or more rows

    • EXPECT_SCALAR

      public static final org.voltdb.Expectation EXPECT_SCALAR
      Expect a result set with a single row and a single column (scalar value)

    • EXPECT_SCALAR_LONG

      public static final org.voltdb.Expectation EXPECT_SCALAR_LONG
      Expect a result with a single row and a single BIGINT column

  • Constructor Details

    • VoltProcedure

      public VoltProcedure()
      End users should not instantiate VoltProcedure instances. Constructor does nothing. All actual initialization is done in the init method.

  • Method Details

    • EXPECT_SCALAR_MATCH

      public static final org.voltdb.Expectation EXPECT_SCALAR_MATCH(long scalar)
      Expect a result with a single row and a single BIGINT column containing the specified value. This factory method constructs an Expectation for the specified value.
      Parameters:
      scalar - The expected value the single row/column should contain
      Returns:
      An Expectation that will cause an exception to be thrown if the value or schema doesn't match

    • getUniqueId

      public long getUniqueId()

      Allow VoltProcedures access to a unique ID generated for each transaction.

      Note that calling it repeatedly within a single transaction will return the same number.

      The id consists of a time based component in the most significant bits followed by a counter, and then a partition id to allow parallel unique number generation.

      Currently, if the host clock moves backwards this call may block while the clock catches up to its previous max. Running NTP with the -x option will prevent this in most cases. It may not be sufficient to 100% avoid this, especially in managed and/or virtualized environments (like AWS). The value will always be unique, but clocks moving backwards may affect system throughput.

      Since this number is initially based on the wall clock time (UTC), it is not guaranteed to be unique across different clusters of VoltDB. If you snapshot, then move time back by 1HR, then load that snapshot into a new VoltDB cluster, you might see duplicate ids for up to 1HR. Since the wall clocks VoltDB uses are UTC, and it takes some amount of time to snapshot and restore, this is a pretty easy corner case to avoid. Note that failure and recovery from disk using command logs will preserve unique id continuity even if the clock shifts.

      In many cases it may make sense to generate unique ids on the client-side and pass them to the server. Please reach out to VoltDB if you have questions about when using this method is appropriate.

      Returns:
      An ID that is unique to this transaction

    • getClusterId

      public int getClusterId()
      Get the ID of cluster that the client connects to.
      Returns:
      An ID that identifies the VoltDB cluster

    • getSeededRandomNumberGenerator

      public Random getSeededRandomNumberGenerator()
      Get a Java RNG seeded with the current transaction id. This will ensure that two procedures for the same transaction, but running on different replicas, can generate an identical stream of random numbers. This is required to endure procedures have deterministic behavior. The RNG is memoized so you can invoke this multiple times within a single procedure.
      Returns:
      A deterministically-seeded java.util.Random instance.

    • getTransactionTime

      public Date getTransactionTime()
      YOU MUST BE RUNNING NTP AND START NTP WITH THE -x OPTION TO GET GOOD BEHAVIOR FROM THIS METHOD - e.g. time always goes forward Get the time that this procedure was accepted into the VoltDB cluster. This is the effective, but not always actual, moment in time this procedure executes. Use this method to get the current time instead of non-deterministic methods. Note that the value will not be unique across transactions as it is only millisecond granularity.
      Returns:
      A java.util.Date instance with deterministic time for all replicas using UTC (Universal Coordinated Time is like GMT).

    • voltQueueSQL

      public void voltQueueSQL(SQLStmt stmt, org.voltdb.Expectation expectation, Object... args)

      Queue the SQL statement for execution with the specified argument list, and an Expectation describing the expected results. If the Expectation is not met then VoltAbortException will be thrown with a description of the expectation that was not met. This exception must not be caught from within the procedure.

      Parameters:
      stmt - Statement to queue for execution.
      expectation - Expectation describing the expected result of executing this SQL statement.
      args - List of arguments to be bound as parameters for the statement
      See Also:

    • voltQueueSQL

      public void voltQueueSQL(SQLStmt stmt, Object... args)
      Queue the SQL statement for execution with the specified argument list.
      Parameters:
      stmt - Statement to queue for execution.
      args - List of arguments to be bound as parameters for the statement
      See Also:

    • voltExecuteSQL

      public VoltTable[] voltExecuteSQL()
      Execute the currently queued SQL statements and return the result tables.
      Returns:
      Result tables generated by executing the queued query statements

    • voltExecuteSQL

      public VoltTable[] voltExecuteSQL(boolean isFinalSQL)
      Execute the currently queued SQL statements and return the result tables. Boolean option allows caller to indicate if this is the final batch for a procedure. If it's final, then additional optimizations can be enabled. Any call to voltExecuteSQL() after calling this with the argument set to true will cause the entire procedure to roll back.
      Parameters:
      isFinalSQL - Is this the final batch for a procedure?
      Returns:
      Result tables generated by executing the queued query statements

    • setAppStatusCode

      public void setAppStatusCode(byte statusCode)
      Set the status code that will be returned to the client. This is not the same as the status code returned by the server. If a procedure sets the status code and then rolls back or causes an error the status code will still be propagated back to the client so it is always necessary to check the server status code first.
      Parameters:
      statusCode - Byte-long application-specific status code.

    • setAppStatusString

      public void setAppStatusString(String statusString)
      Set the string that will be turned to the client. This is not the same as the status string returned by the server. If a procedure sets the status string and then rolls back or causes an error the status string will still be propagated back to the client so it is always necessary to check the server status code first.
      Parameters:
      statusString - Application specific status string.

    • getPartitionId

      public int getPartitionId()

    • getTransactionId

      public long getTransactionId()