Package 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
    invalid reference 
    #complete(boolean)
    method or cancel the transaction via the
    invalid reference 
    #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:

  • invalid reference 
    #complete(boolean)
  • invalid reference 
    #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
    Description
    static enum 
    Transaction.TransactionState
     

  • Method Summary

    Modifier and Type
    Method
    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 Details

    • 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)