Package com.amazonaws.kinesisvideo.producer

Class KinesisVideoFragmentAck

  • @Immutable
@ThreadSafe
public class KinesisVideoFragmentAck
extends Object
    Represents an acknowledgement received from Amazon Kinesis Video Streams for a fragment.

    This class encapsulates the acknowledgement information sent back by the Kinesis Video Streams service when fragments are processed. Acknowledgements provide feedback about the status of fragments as they move through different stages of processing in the service pipeline.

    Fragment acknowledgements can indicate various states such as:

    • BUFFERING - Fragment started buffering on the ingestion host
    • RECEIVED - Fragment has been received and parsed
    • PERSISTED - Fragment has been persisted to storage
    • ERROR - Fragment sent for ingestion encountered an error, check the error code reference in the PutMedia API documentation
    • IDLE - Keep-alive acknowledgement to maintain connection

    Thread Safety: This class is immutable and thread-safe.

    Note: This class structure must match the Frame declaration in native code located in /client/Include.h to ensure proper JNI interoperability.

    See Also:
    FragmentAckType, PutMedia API Documentation, Producer SDK Documentation

    • Constructor Detail

      • KinesisVideoFragmentAck

        public KinesisVideoFragmentAck​(@Nonnull
                               FragmentAckType ackType,
                               long timestamp,
                               @Nonnull
                               String sequenceNumber,
                               int result)
        Constructs a new KinesisVideoFragmentAck with the specified parameters.

        This is the primary constructor that accepts a FragmentAckType object directly, providing type safety and better API design. This constructor performs runtime validation of all non-null parameters.

        Parameters:
        ackType - the acknowledgement type
        timestamp - the fragment timecode with milliseconds precision, which may be relative or absolute depending on the configuration of the stream
        sequenceNumber - the unique sequence number for the fragment
        result - the service call result code (HTTP status or error code)
        Throws:
        IllegalArgumentException - if ackType or sequenceNumber is null
        See Also:
        FragmentAckType

    • Method Detail

      • getVersion

        @CalledByNativeCode
public int getVersion()
        Returns the version of the fragment acknowledgement format.

        This version number helps maintain compatibility between different versions of this struct in the native layer. The current version is 0.

        Returns:
        the current version number

      • getAckType

        @Nonnull
@CalledByNativeCode
public FragmentAckType getAckType()
        Returns the acknowledgement type indicating the fragment's processing state.

        The acknowledgement type provides information about where the fragment is in the service processing pipeline, such as whether it's being buffered, has been received, persisted, or encountered an error.

        Returns:
        the acknowledgement type
        See Also:
        FragmentAckType

      • getSequenceNumber

        @Nonnull
@CalledByNativeCode
public String getSequenceNumber()
        Returns the unique sequence number identifying the fragment.

        This sequence number is assigned by the Kinesis Video Streams service and uniquely identifies each fragment within a stream. It can be used to track fragment processing and correlate acknowledgements with the original fragments sent to the service.

        Returns:
        the fragment sequence number (never null)

      • getResult

        @CalledByNativeCode
public int getResult()
        Returns the service call result code for the acknowledgement.

        This result code indicates the outcome of the fragment:

        • HTTP 200 (OK) - Successful processing (Buffering, Received, Persisted)
        • HTTP 40xx - Client errors (e.g., malformed fragment)
        • HTTP 45xx - Client errors related to KMS
        • HTTP 50xx - Server errors (e.g., service unavailable)

        If the code is not 200, then this acknowledgement type is FragmentAckType.FRAGMENT_ACK_TYPE_ERROR.

        Returns:
        the service call result code
        See Also:
        StreamInfoConstants.HTTP_OK

      • toString

        public String toString()
        Returns a JSON-formatted string representation of the fragment acknowledgement.

        The returned string follows the format used by the Kinesis Video Streams PutMedia API for acknowledgement messages. The format includes:

        • EventType - The acknowledgement type (BUFFERING, RECEIVED, etc.)
        • FragmentTimecode - The fragment timestamp
        • FragmentNumber - The unique sequence number
        • ErrorId - The error code (only included for non-successful results)

        Example output for successful acknowledgement: 

         {
     Acknowledgement: {
         "EventType": "PERSISTED"
         "FragmentTimecode": 1234567890,
         "FragmentNumber": "12345678901234567890"
     }
 }

        Example output for error acknowledgement: 

         {
     Acknowledgement: {
         "EventType": "ERROR"
         "FragmentTimecode": 1234567890,
         "FragmentNumber": "12345678901234567890",
         "ErrorId": 400
     }
 }

        Overrides:
        toString in class Object
        Returns:
        a JSON-formatted string representation of the acknowledgement
        See Also:
        PutMedia API Documentation