PartitionReceiver Interface

public interface PartitionReceiver

This is a logical representation of receiving from a EventHub partition.

A PartitionReceiver is tied to a ConsumerGroup + EventHub Partition combination.

  • If an epoch based PartitionReceiver (i.e., PartitionReceiver.getEpoch != 0) is created, EventHubs service will guarantee only 1 active receiver exists per ConsumerGroup + Partition combo. This is the recommended approach to create a PartitionReceiver.

  • Multiple receivers per ConsumerGroup + Partition combo can be created using non-epoch receivers.

Field Summary

Modifier and Type Field and Description
int DEFAULT_PREFETCH_COUNT
int MAXIMUM_PREFETCH_COUNT
int MINIMUM_PREFETCH_COUNT
long NULL_EPOCH

Method Summary

Modifier and Type Method and Description
CompletableFuture<Void> close()
void closeSync()
long getEpoch()

Get the epoch value that this receiver is currently using for partition ownership.

A value of 0 means this receiver is not an epoch-based receiver.

EventPosition getEventPosition()

Get the EventPosition that corresponds to an EventData which was returned last by the receiver.

This value will not be populated, unless the knob setReceiverRuntimeMetricEnabled(boolean value) is set. Note that EventPosition object is initialized using SequenceNumber and other parameters are not set and get will return null.

String getPartitionId()

Get EventHubs partition identifier.

Duration getReceiveTimeout()
ReceiverRuntimeInformation getRuntimeInformation()

Gets the temporal ReceiverRuntimeInformation for this EventHub partition. In general, this information is a representation of, where this PartitionReceiver's end of stream is, at the time getRetrievalTime().

This value will not be populated, unless the knob setReceiverRuntimeMetricEnabled(boolean value) is set. This value will be refreshed every time an EventData is consumed from PartitionReceiver. For ex: if no events have been consumed, then this value is not populated.

CompletableFuture<Iterable<EventData>>

receive(final int maxEventCount)

Receive a batch of EventData's from an EventHub partition

Sample code (sample uses sync version of the api but concept are identical):

EventHubClient client = EventHubClient.createSync("__connection__");
PartitionReceiver receiver = client.createPartitionReceiverSync("ConsumerGroup1", "1");
Iterable{<}EventData{>} receivedEvents = receiver.receiveSync();

while (true)

{

    int batchSize = 0;

    if (receivedEvents != null)

    {

        for(EventData receivedEvent: receivedEvents)

        {

            System.out.println(String.format("Message Payload: %s", new String(receivedEvent.getBytes(), Charset.defaultCharset())));

            System.out.println(String.format("Offset: %s, SeqNo: %s, EnqueueTime: %s",

                receivedEvent.getSystemProperties().getOffset(),

                receivedEvent.getSystemProperties().getSequenceNumber(),

                receivedEvent.getSystemProperties().getEnqueuedTime()));

            batchSize++;

        }

    }

    System.out.println(String.format("ReceivedBatch Size: %s", batchSize));

    receivedEvents = receiver.receiveSync();

}

default Iterable<EventData>

receiveSync(final int maxEventCount)

Synchronous version of receive(final int maxEventCount).

CompletableFuture<Void> setReceiveHandler(final PartitionReceiveHandler receiveHandler)

Register a receive handler that will be called when an event is available. A PartitionReceiveHandler is a handler that allows user to specify a callback for event processing and error handling in a receive pump model.

CompletableFuture<Void> setReceiveHandler(final PartitionReceiveHandler receiveHandler, final boolean invokeWhenNoEvents)

Register a receive handler that will be called when an event is available. A PartitionReceiveHandler is a handler that allows user to specify a callback for event processing and error handling in a receive pump model.

void setReceiveTimeout(Duration value)

Field Details

DEFAULT_PREFETCH_COUNT

public int DEFAULT_PREFETCH_COUNT= 500

MAXIMUM_PREFETCH_COUNT

public int MAXIMUM_PREFETCH_COUNT= 4000

MINIMUM_PREFETCH_COUNT

public int MINIMUM_PREFETCH_COUNT= 1

NULL_EPOCH

public long NULL_EPOCH= 0

Method Details

close

public CompletableFuture close()

closeSync

public void closeSync()

getEpoch

public long getEpoch()

Get the epoch value that this receiver is currently using for partition ownership.

A value of 0 means this receiver is not an epoch-based receiver.

Returns:

the epoch value that this receiver is currently using for partition ownership.

getEventPosition

public EventPosition getEventPosition()

Get the EventPosition that corresponds to an EventData which was returned last by the receiver.

This value will not be populated, unless the knob setReceiverRuntimeMetricEnabled(boolean value) is set. Note that EventPosition object is initialized using SequenceNumber and other parameters are not set and get will return null.

Returns:

the EventPosition object.

getPartitionId

public String getPartitionId()

Get EventHubs partition identifier.

Returns:

The identifier representing the partition from which this receiver is fetching data

getReceiveTimeout

public Duration getReceiveTimeout()

getRuntimeInformation

public ReceiverRuntimeInformation getRuntimeInformation()

Gets the temporal ReceiverRuntimeInformation for this EventHub partition. In general, this information is a representation of, where this PartitionReceiver's end of stream is, at the time getRetrievalTime().

This value will not be populated, unless the knob setReceiverRuntimeMetricEnabled(boolean value) is set. This value will be refreshed every time an EventData is consumed from PartitionReceiver. For ex: if no events have been consumed, then this value is not populated.

Returns:

receiver runtime information

receive

public CompletableFuture<>> receive(final int maxEventCount)

Receive a batch of EventData's from an EventHub partition

Sample code (sample uses sync version of the api but concept are identical):

EventHubClient client = EventHubClient.createSync("__connection__");
PartitionReceiver receiver = client.createPartitionReceiverSync("ConsumerGroup1", "1");
Iterable{<}EventData{>} receivedEvents = receiver.receiveSync();

while (true)

{

    int batchSize = 0;

    if (receivedEvents != null)

    {

        for(EventData receivedEvent: receivedEvents)

        {

            System.out.println(String.format("Message Payload: %s", new String(receivedEvent.getBytes(), Charset.defaultCharset())));

            System.out.println(String.format("Offset: %s, SeqNo: %s, EnqueueTime: %s",

                receivedEvent.getSystemProperties().getOffset(),

                receivedEvent.getSystemProperties().getSequenceNumber(),

                receivedEvent.getSystemProperties().getEnqueuedTime()));

            batchSize++;

        }

    }

    System.out.println(String.format("ReceivedBatch Size: %s", batchSize));

    receivedEvents = receiver.receiveSync();

}

Parameters:

maxEventCount - maximum number of EventData's that this call should return

Returns:

A completableFuture that will yield a batch of EventData's from the partition on which this receiver is created. Returns 'null' if no EventData is present.

receiveSync

public default Iterable receiveSync(final int maxEventCount)

Synchronous version of receive(final int maxEventCount).

Parameters:

maxEventCount - maximum number of EventData's that this call should return

Returns:

Batch of EventData's from the partition on which this receiver is created. Returns 'null' if no EventData is present.

Throws:

EventHubException - if ServiceBus client encountered any unrecoverable/non-transient problems during receive(final int maxEventCount)

setReceiveHandler

public CompletableFuture setReceiveHandler(final PartitionReceiveHandler receiveHandler)

Register a receive handler that will be called when an event is available. A PartitionReceiveHandler is a handler that allows user to specify a callback for event processing and error handling in a receive pump model.

Parameters:

receiveHandler - An implementation of PartitionReceiveHandler. Setting this handler to null will stop the receive pump.

Returns:

A completableFuture which sets receiveHandler

setReceiveHandler

public CompletableFuture setReceiveHandler(final PartitionReceiveHandler receiveHandler, final boolean invokeWhenNoEvents)

Register a receive handler that will be called when an event is available. A PartitionReceiveHandler is a handler that allows user to specify a callback for event processing and error handling in a receive pump model.

Parameters:

receiveHandler - An implementation of PartitionReceiveHandler
invokeWhenNoEvents - flag to indicate whether the PartitionReceiveHandler#onReceive(Iterable) should be invoked when the receive call times out

Returns:

A completableFuture which sets receiveHandler

setReceiveTimeout

public void setReceiveTimeout(Duration value)

Parameters:

value

Applies to