org.voltdb

Class VoltProcedure

java.lang.Object

org.voltdb.VoltProcedure

public abstract class VoltProcedure
extends java.lang.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 and 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 and Description
static org.voltdb.Expectation	EXPECT_EMPTY Expect an empty result set (0 rows)
static org.voltdb.Expectation	EXPECT_NON_EMPTY Expect a result set with one or more rows
static org.voltdb.Expectation	EXPECT_ONE_ROW Expect a result set with exactly one row
static org.voltdb.Expectation	EXPECT_SCALAR Expect a result set with a single row and a single column (scalar value)
static org.voltdb.Expectation	EXPECT_SCALAR_LONG Expect a result with a single row and a single BIGINT column
static org.voltdb.Expectation	EXPECT_ZERO_OR_ONE_ROW Expect a result set with one or no rows

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static 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()
java.util.Random	getSeededRandomNumberGenerator() Get a Java RNG seeded with the current transaction id.
java.util.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(java.lang.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, org.voltdb.Expectation expectation, java.lang.Object... args) Queue the SQL statement for execution with the specified argument list, and an Expectation describing the expected results.
void	voltQueueSQL(SQLStmt stmt, java.lang.Object... args) Queue the SQL statement for execution with the specified argument list.

Methods inherited from class java.lang.Object

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

Field Detail

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 Detail

VoltProcedure

public VoltProcedure()

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

Method Detail

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 java.util.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 java.util.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,
                         java.lang.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:

List of allowable parameter types

voltQueueSQL

public void voltQueueSQL(SQLStmt stmt,
                         java.lang.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:

List of allowable parameter types

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(java.lang.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()