org.apache.kudu.client

Class KuduTransaction

java.lang.Object

org.apache.kudu.client.KuduTransaction

All Implemented Interfaces:

AutoCloseable

@InterfaceAudience.Public
 @InterfaceStability.Unstable
public class KuduTransaction
extends Object
implements AutoCloseable

A handle for a multi-row transaction in Kudu.

Once created using KuduClient.newTransaction() or deserialize(byte[], org.apache.kudu.client.AsyncKuduClient) methods, an instance of this class can be used to commit or rollback the underlying multi-row transaction. To issue write operations as a part of the transaction, use the newKuduSession() or newAsyncKuduSession() methods to create a new transactional session and apply write operations using it.

The KuduTransaction implements AutoCloseable and should be used with try-with-resource code construct. Once an object of this class is constructed, it starts sending automatic keep-alive heartbeat messages to keep the underlying transaction open. Once the object goes out of scope and close() is automatically called by the Java runtime (or the method is called explicitly), the heartbeating stops and the transaction is automatically aborted by the system after not receiving heartbeat messages for a few keep-alive intervals.

Method Summary

Modifier and Type	Method and Description
void	close() Stop keepalive heartbeating, if any was in progress for this transaction handle.
void	commit() Commit the multi-row distributed transaction represented by this handle.
static KuduTransaction	deserialize(byte[] buf, AsyncKuduClient client) Re-create KuduTransaction object given its serialized representation.
boolean	isCommitComplete() Check whether the commit phase for a transaction is complete.
AsyncKuduSession	newAsyncKuduSession() Create a new AsyncKuduSession based on this transaction.
KuduSession	newKuduSession() Create a new KuduSession based on this transaction.
void	rollback() Rollback the multi-row distributed transaction represented by this object.
byte[]	serialize() A shortcut for the serialize(SerializationOptions) method invoked with default-constructed KuduTransaction.SerializationOptions.
byte[]	serialize(org.apache.kudu.client.KuduTransaction.SerializationOptions options) Export information on the underlying transaction in a serialized form.
void	startCommit() Start committing the multi-row distributed transaction represented by this handle.

Methods inherited from class java.lang.Object

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

Method Detail

newAsyncKuduSession

public AsyncKuduSession newAsyncKuduSession()

Create a new AsyncKuduSession based on this transaction.

All write operations using the result session will be performed in the context of this transaction.

Returns:

a new AsyncKuduSession instance

newKuduSession

public KuduSession newKuduSession()

Create a new KuduSession based on this transaction.

All write operations using the result session will be performed in the context of this transaction.

Returns:

a new KuduSession instance

commit

public void commit()
            throws KuduException

Commit the multi-row distributed transaction represented by this handle.

This method starts committing the transaction and awaits for the commit phase to finalize.

Throws:

KuduException - if something went wrong

startCommit

public void startCommit()
                 throws KuduException

Start committing the multi-row distributed transaction represented by this handle.

This method only starts committing the transaction, not awaiting for the commit phase to finalize. Use isCommitComplete() to check whether the transaction is committed.

Throws:

KuduException - if something went wrong upon starting to commit

isCommitComplete

public boolean isCommitComplete()
                         throws KuduException

Check whether the commit phase for a transaction is complete.

Returns:

true if transaction has finalized, otherwise false

Throws:

NonRecoverableException - with Status.Aborted() if transaction has been or is being aborted

NonRecoverableException - with Status.IllegalState() if transaction is still open (i.e. commit() hasn't been called yet)

NonRecoverableException - with Status.NotSupported() if transaction is in unexpected state (non-compatible backend?)

KuduException - if an error happens while querying the system about the state of the transaction

rollback

public void rollback()
              throws KuduException

Rollback the multi-row distributed transaction represented by this object.

This method initiates rolling back the transaction and returns right after that. The system takes care of the rest. Once the control returns and no exception is thrown, a client have a guarantee that all write operations issued in the context of this transaction cannot be seen seen outside.

Throws:

KuduException - if something went wrong

serialize

public byte[] serialize(org.apache.kudu.client.KuduTransaction.SerializationOptions options)
                 throws IOException

Export information on the underlying transaction in a serialized form.

This method transforms this handle into its serialized representation.

The serialized information on a Kudu transaction can be passed among different Kudu clients running at multiple nodes, so those separate Kudu clients can perform operations to be a part of the same distributed transaction. The resulting string is referred as "transaction token" and it can be deserialized into a transaction handle (i.e. an object of this class) via the deserialize(byte[], org.apache.kudu.client.AsyncKuduClient) method.

This method doesn't perform any RPC under the hood.

The representation of the data in the serialized form (i.e. the format of a Kudu transaction token) is an implementation detail, not a part of the public API and can be changed without notice.

Returns:

the serialized form of this transaction handle

Throws:

IOException - if serialization fails

serialize

public byte[] serialize()
                 throws IOException

A shortcut for the serialize(SerializationOptions) method invoked with default-constructed KuduTransaction.SerializationOptions.

Throws:

IOException

deserialize

public static KuduTransaction deserialize(byte[] buf,
                                          AsyncKuduClient client)
                                   throws IOException

Re-create KuduTransaction object given its serialized representation.

This method doesn't perform any RPC under the hood. The newly created object automatically does or does not send keep-alive messages depending on the KuduTransaction.SerializationOptions.isKeepaliveEnabled() setting when the original KuduTransaction object was serialized using serialize(org.apache.kudu.client.KuduTransaction.SerializationOptions) method.

Parameters:

client - Client instance to bound the result object to

buf - serialized representation of a KuduTransaction object

Returns:

Operation result status.

Throws:

IOException - if deserialization fails

close

public void close()

Stop keepalive heartbeating, if any was in progress for this transaction handle.

This method is called automatically when the object goes out of scope as prescribed for AutoCloseable.

This method doesn't throw according to the recommendations for AutoCloseable.close(). In case of an error, this method just logs the corresponding error message.

Specified by:

close in interface AutoCloseable