PartitionReceiver Interface

  • Reference
Package:
com.microsoft.azure.eventhubs
Maven Artifact:
com.microsoft.azure:azure-eventhubs:3.2.2

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
static final int DEFAULT_PREFETCH_COUNT
static final int MAXIMUM_PREFETCH_COUNT
static final int MINIMUM_PREFETCH_COUNT
static final long NULL_EPOCH

Method Summary

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

Get the epoch value that this receiver is currently using for partition ownership.
abstract EventPosition getEventPosition()

Get the EventPosition that corresponds to an EventData which was returned last by the receiver.
abstract boolean getIsOpen()

Determine the current state of the receiver.
abstract String getPartitionId()

Get EventHubs partition identifier.
abstract Duration getReceiveTimeout()
abstract ReceiverRuntimeInformation getRuntimeInformation()

Gets the temporal ReceiverRuntimeInformation for this EventHub partition.
abstract CompletableFuture<Iterable<EventData>> receive(int maxEventCount)

Receive a batch of EventData's from an EventHub partition
default Iterable<EventData> receiveSync(int maxEventCount)

Synchronous version of #receive.
abstract CompletableFuture<Void> setReceiveHandler(PartitionReceiveHandler receiveHandler)

Register a receive handler that will be called when an event is available.
abstract CompletableFuture<Void> setReceiveHandler(PartitionReceiveHandler receiveHandler, boolean invokeWhenNoEvents)

Register a receive handler that will be called when an event is available.
abstract void setReceiveTimeout(Duration value)

Field Details

DEFAULT_PREFETCH_COUNT

public static final int DEFAULT_PREFETCH_COUNT

MAXIMUM_PREFETCH_COUNT

public static final int MAXIMUM_PREFETCH_COUNT

MINIMUM_PREFETCH_COUNT

public static final int MINIMUM_PREFETCH_COUNT

NULL_EPOCH

public static final long NULL_EPOCH

Method Details

close

public abstract CompletableFuture close()

closeSync

public abstract void closeSync()

Throws:

getEpoch

public abstract 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 abstract 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.

getIsOpen

public abstract boolean getIsOpen()

Determine the current state of the receiver.

Returns:

false if the receiver is closing or has been closed, true if the receiver is open and ready to use.

getPartitionId

public abstract String getPartitionId()

Get EventHubs partition identifier.

Returns:

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

getReceiveTimeout

public abstract Duration getReceiveTimeout()

getRuntimeInformation

public abstract 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 abstract CompletableFuture<>> receive(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 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(int maxEventCount)

Synchronous version of #receive.

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

setReceiveHandler

public abstract CompletableFuture setReceiveHandler(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 abstract CompletableFuture setReceiveHandler(PartitionReceiveHandler receiveHandler, 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 onReceive(Iterable<EventData> events) should be invoked when the receive call times out

Returns:

A completableFuture which sets receiveHandler

setReceiveTimeout

public abstract void setReceiveTimeout(Duration value)

Parameters:

value

Applies to