com.h3c.of.ctl

## Interface TxRxControl

-     public interface TxRxControl

  Message transmission recording control API.

  This interface has two functions:

  - It provides the controls to enable the recording of all transmitted and received OpenFlow messages for a short period of time.
  - It exposes the consumer side of the TX/RX message queue, so that the recorded messages can be retrieved.
  The queue implementation is an unbounded, blocking queue.

  Note that the messages reported through this mechanism include pseudo-messages marking the initial connection requests from the switches, as well as the "handshaking" and "heartbeat" messages handled internally by the controller. These messages are not visible above `ControllerService`.

  The intended use of this mechanism is to allow a logging service to record all the OpenFlow messages for a brief span of time, for field support or debugging purposes.

  See Also:
    `ControllerMx`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isEmpty()` Returns `true` if the TX/RX queue contains no elements.
    `boolean` | `isRecording()` Returns true if TX/RX messages are being recorded.
    `boolean` | `isTriggerWaiting()` Returns true if a trigger has been set, but has not yet fired.
    `MessageEvent` | `poll(long timeoutMs)` Retrieves and removes the head of the TX/RX message event queue, waiting up to the specified number of milliseconds for an element to become available.
    `int` | `size()` Returns the number of elements in the TX/RX queue.
    `void` | `startRecording(int seconds)` Enables message recording for the specified amount of time, starting immediately.
    `void` | `stopRecording()` Shuts off recording of messages immediately, and clears any trigger that might have been set.
    `MessageEvent` | `take()` Retrieves and removes the head of the TX/RX message event queue, waiting if necessary until an element becomes available.
    `void` | `triggerRecording(TxRxTrigger trigger, int seconds)` Enables message recording for the specified amount of time, starting when the specified trigger condition is met.

- - ### Method Detail

    - #### startRecording

          void startRecording(int seconds)

      Enables message recording for the specified amount of time, starting immediately. After the specified amount of time has elapsed, recording will shut off automatically.

      An exception will be thrown if we are already recording, or if a trigger has been set and is waiting to fire. To clear this condition, call `stopRecording()`.

      Parameters:
        `seconds` - the number of seconds to elapse before message recording is shut off
      Throws:
        `IllegalArgumentException` - if seconds is < 1
        `IllegalStateException` - if recording is already in progress

    - #### triggerRecording

          void triggerRecording(TxRxTrigger trigger,
                              int seconds)

      Enables message recording for the specified amount of time, starting when the specified trigger condition is met. After the specified amount of time has elapsed, recording will shut off automatically.

      An exception will be thrown if we are already recording, or if a trigger has been set and is waiting to fire. To clear this condition, call `stopRecording()`.

      This is a place holder method: not yet implemented.

      Parameters:
        `trigger` - the condition required to trigger the start of recording
        `seconds` - the number of seconds to elapse after recording has started, before message recording is shut off
      Throws:
        `NullPointerException` - if trigger is null
        `IllegalArgumentException` - if seconds is < 1
        `IllegalStateException` - if recording is already in progress

    - #### stopRecording

          void stopRecording()

      Shuts off recording of messages immediately, and clears any trigger that might have been set.

    - #### isRecording

          boolean isRecording()

      Returns true if TX/RX messages are being recorded.
      Returns:
        `true` if TX/RX messages are being recorded

    - #### isTriggerWaiting

          boolean isTriggerWaiting()

      Returns true if a trigger has been set, but has not yet fired.
      Returns:
        `true` if a trigger is set but has not been fired

    - #### take

          MessageEvent take()
                            throws InterruptedException

      Retrieves and removes the head of the TX/RX message event queue, waiting if necessary until an element becomes available.

      This method blocks if there are no elements in the queue.

      Returns:
        the head of the TX/RX queue
      Throws:
        `InterruptedException` - if interrupted while waiting

    - #### poll

          MessageEvent poll(long timeoutMs)
                            throws InterruptedException

      Retrieves and removes the head of the TX/RX message event queue, waiting up to the specified number of milliseconds for an element to become available.
      Parameters:
        `timeoutMs` - the maximum number of milliseconds to wait
      Returns:
        the head of the TX/RX queue, or `null` if the specified wait time elapses before an element is available
      Throws:
        `InterruptedException` - if interrupted while waiting

    - #### size

          int size()

      Returns the number of elements in the TX/RX queue.
      Returns:
        the number of elements in the queue

    - #### isEmpty

          boolean isEmpty()

      Returns `true` if the TX/RX queue contains no elements.
      Returns:
        `true` if the queue contains no elements

Copyright © 2014. All Rights Reserved.