org.apache.nifi.remote

Interface Transaction

All Known Implementing Classes:

AbstractTransaction, HttpClientTransaction, SocketClientTransaction

public interface Transaction

Provides a transaction for performing site-to-site data transfers.

A Transaction is created by calling the createTransaction(TransferDirection) method of a SiteToSiteClient. The resulting Transaction can be used to either send or receive data but not both. A new Transaction must be created in order perform the other operation.

The general flow of execute of a Transaction is as follows:

1. Create the transaction as described above.
2. Send data via the send(DataPacket) method or receive data via the receive() method. This method will be called 1 or more times. In the case of receive, this method should be called until the method returns null, signifying that the remote instance is finished sending data. Note: receive() should not be called a second time without first fully consuming the stream from the previous Packet that was received.
3. Confirm the transaction via the confirm() method.
4. Either complete the transaction via the #complete(boolean) method or cancel the transaction via the #cancel() method.

It is important that the Transaction be terminated in order to free the resources held by the Transaction. If a Transaction is not terminated, its resources will not be freed and if the Transaction holds connections from a connection pool, the connections in that pool will eventually become exhausted. A Transaction is terminated by calling one of the following methods:

• #complete(boolean)
• #cancel()
• error()

If at any point an IOException is thrown from one of the methods of the Transaction, that Transaction is automatically closed via a call to error().

The Transaction class should not be assumed to be thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Transaction.TransactionState

Method Summary

Modifier and Type	Method and Description
void	cancel(String explanation) Cancels this transaction, indicating to the sender that the data has not been successfully received so that the sender can retry or handle however is appropriate.
TransactionCompletion	complete() Completes the transaction and indicates to both the sender and receiver that the data transfer was successful.
void	confirm() Confirms the data that was sent or received by comparing CRC32's of the data sent and the data received.
void	error() Sets the TransactionState of the Transaction to Transaction.TransactionState.ERROR, and closes the Transaction.
Communicant	getCommunicant()
Transaction.TransactionState	getState()
DataPacket	receive() Retrieves information from the remote NiFi instance, if any is available.
void	send(byte[] content, Map<String,String> attributes) Sends the given byte array as the content of a DataPacket along with the provided attributes
void	send(DataPacket dataPacket) Sends information to the remote NiFi instance.

Method Detail

send

void send(DataPacket dataPacket)
   throws IOException

Sends information to the remote NiFi instance.

Parameters:

dataPacket - the data packet to send

Throws:

IOException - if unable to send

send

void send(byte[] content,
          Map<String,String> attributes)
   throws IOException

Sends the given byte array as the content of a DataPacket along with the provided attributes

Parameters:

content - to send

attributes - of the content

Throws:

IOException - if unable to send

receive

DataPacket receive()
            throws IOException

Retrieves information from the remote NiFi instance, if any is available. If no data is available, will return null. It is important to consume all data from the remote NiFi instance before attempting to call confirm(). This is because the sender is always responsible for determining when the Transaction has finished. This is done in order to prevent the need for a round-trip network request to receive data for each data packet.

Returns:

the DataPacket received, or null if there is no more data to receive.

Throws:

IOException - if unable to receive

confirm

void confirm()
      throws IOException

Confirms the data that was sent or received by comparing CRC32's of the data sent and the data received.

Even if the protocol being used to send the data is reliable and guarantees ordering of packets (such as TCP), it is still required that we confirm the transaction before completing the transaction. This is done as "safety net" or a defensive programming technique. Mistakes happen, and this mechanism helps to ensure that if a bug exists somewhere along the line that we do not end up sending or receiving corrupt data. If the CRC32 of the sender and the CRC32 of the receiver do not match, an IOException will be thrown and both the sender and receiver will cancel the transaction automatically.

If the TransferDirection of this Transaction is RECEIVE, this method will throw an Exception unless all data from the remote instance has been consumed (i.e., a call to receive() returns null).

If the TransferDirection of this Transaction is SEND, calling this method dictates that no more data will be sent in this transaction. I.e., there will be no more calls to send(DataPacket).

Throws:

IOException - if unable to confirm transaction

complete

TransactionCompletion complete()
                        throws IOException

Completes the transaction and indicates to both the sender and receiver that the data transfer was successful.

Returns:

a TransactionCompletion that contains details about the Transaction

Throws:

IOException - if unable to complete

cancel

void cancel(String explanation)
     throws IOException

Cancels this transaction, indicating to the sender that the data has not been successfully received so that the sender can retry or handle however is appropriate.

Parameters:

explanation - an explanation to tell the other party why the transaction was canceled.

Throws:

IOException - if unable to cancel

error

void error()

Sets the TransactionState of the Transaction to Transaction.TransactionState.ERROR, and closes the Transaction. The underlying connection should not be returned to a connection pool in this case.

getState

Transaction.TransactionState getState()
                               throws IOException

Returns:

the current state of the Transaction.

Throws:

IOException - ioe

getCommunicant

Communicant getCommunicant()

Returns:

a Communicant that represents the other side of this Transaction (i.e., the remote NiFi instance)