Class EventHubBufferedProducerClient
- All Implemented Interfaces:
Closeable
,AutoCloseable
EventData
to a specific Event Hub. Depending on the options
specified when events are enqueued, they may be automatically assigned to a partition, grouped according to the
specified partition key, or assigned a specifically requested partition.
The EventHubBufferedProducerClient
does not publish immediately, instead using a deferred model where events
are collected into a buffer so that they may be efficiently batched and published when the batch is full or the
maxWaitTime
has elapsed with no new events
enqueued.
This model is intended to shift the burden of batch management from callers, at the cost of non-deterministic timing, for when events will be published. There are additional trade-offs to consider, as well:
- If the application crashes, events in the buffer will not have been published. To
prevent data loss, callers are encouraged to track publishing progress using
onSendBatchFailed
andonSendBatchSucceeded
. - Events specifying a partition key may be assigned a different partition than those using the same key with other producers.
- In the unlikely event that a partition becomes temporarily unavailable,
the
EventHubBufferedProducerClient
may take longer to recover than other producers.
In scenarios where it is important to have events published immediately with a deterministic outcome, ensure that
partition keys are assigned to a partition consistent with other publishers, or where maximizing availability is a
requirement, using EventHubProducerAsyncClient
or EventHubProducerClient
is recommended.
Creating an EventHubBufferedProducerClient
TokenCredential credential = new DefaultAzureCredentialBuilder().build(); EventHubBufferedProducerClient client = new EventHubBufferedProducerClientBuilder() .connectionString("event-hub-namespace-connection-string", "event-hub-name") .onSendBatchSucceeded(succeededContext -> { System.out.println("Successfully published events to: " + succeededContext.getPartitionId()); }) .onSendBatchFailed(failedContext -> { System.out.printf("Failed to published events to %s. Error: %s%n", failedContext.getPartitionId(), failedContext.getThrowable()); }) .buildClient();
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Disposes of the producer and all its resources.enqueueEvent
(EventData eventData) Enqueues anEventData
into the buffer to be published to the Event Hub.enqueueEvent
(EventData eventData, SendOptions options) Enqueues anEventData
into the buffer to be published to the Event Hub.enqueueEvents
(Iterable<EventData> events) Enqueues a set ofEventData
into the buffer to be published to the Event Hub.enqueueEvents
(Iterable<EventData> events, SendOptions options) Enqueues a set ofEventData
into the buffer to be published to the Event Hub.void
flush()
Attempts to publish all events in the buffer immediately.int
Gets the total number of events that are currently buffered and waiting to be published, across all partitions.int
getBufferedEventCount
(String partitionId) Gets the number of events that are buffered and waiting to be published for a given partition.Gets the Event Hub name this client interacts with.Retrieves information about an Event Hub, including the number of partitions present and their identifiers.Gets the fully qualified Event Hubs namespace that the connection is associated with.com.azure.core.util.IterableStream<String>
Retrieves the identifiers for the partitions of an Event Hub.getPartitionProperties
(String partitionId) Retrieves information about a specific partition for an Event Hub, including elements that describe the available events in the partition event stream.
-
Method Details
-
getFullyQualifiedNamespace
Gets the fully qualified Event Hubs namespace that the connection is associated with. This is likely similar to{yournamespace}.servicebus.windows.net
.- Returns:
- The fully qualified Event Hubs namespace that the connection is associated with
-
getEventHubName
Gets the Event Hub name this client interacts with.- Returns:
- The Event Hub name this client interacts with.
-
getEventHubProperties
Retrieves information about an Event Hub, including the number of partitions present and their identifiers.- Returns:
- The set of information for the Event Hub that this client is associated with.
-
getPartitionIds
Retrieves the identifiers for the partitions of an Event Hub.- Returns:
- A stream of identifiers for the partitions of an Event Hub.
-
getPartitionProperties
Retrieves information about a specific partition for an Event Hub, including elements that describe the available events in the partition event stream.- Parameters:
partitionId
- The unique identifier of a partition associated with the Event Hub.- Returns:
- The set of information for the requested partition under the Event Hub this client is associated with.
- Throws:
NullPointerException
- ifpartitionId
is null.IllegalArgumentException
- ifpartitionId
is empty.
-
getBufferedEventCount
public int getBufferedEventCount()Gets the total number of events that are currently buffered and waiting to be published, across all partitions.- Returns:
- The total number of events that are currently buffered and waiting to be published, across all partitions.
-
getBufferedEventCount
Gets the number of events that are buffered and waiting to be published for a given partition.- Parameters:
partitionId
- The partition identifier.- Returns:
- The number of events that are buffered and waiting to be published for a given partition.
- Throws:
NullPointerException
- ifpartitionId
is null.IllegalArgumentException
- ifpartitionId
is empty.
-
enqueueEvent
Enqueues anEventData
into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that theeventData
has been enqueued. When this call returns, theeventData
has been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.- Parameters:
eventData
- The event to be enqueued into the buffer and, later, published.- Returns:
- The total number of events that are currently buffered and waiting to be published, across all partitions.
- Throws:
NullPointerException
- ifeventData
is null.IllegalStateException
- if the producer was closed while queueing an event.
-
enqueueEvent
Enqueues anEventData
into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that theeventData
has been enqueued. When this call returns, theeventData
has been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.- Parameters:
eventData
- The event to be enqueued into the buffer and, later, published.options
- The set of options to apply when publishing this event. If partitionKey and partitionId are not set, then the event is distributed round-robin amongst all the partitions.- Returns:
- The total number of events that are currently buffered and waiting to be published, across all partitions.
- Throws:
NullPointerException
- ifeventData
oroptions
is null.IllegalArgumentException
- ifgetPartitionId
is set and is not valid.IllegalStateException
- if the producer was closed while queueing an event.
-
enqueueEvents
Enqueues a set ofEventData
into the buffer to be published to the Event Hub. If there is insufficient capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that all EventData in theevents
set have been enqueued. When this call returns, theevents
have been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.- Parameters:
events
- The set of events to be enqueued into the buffer and, later, published.- Returns:
- The total number of events that are currently buffered and waiting to be published, across all partitions.
- Throws:
NullPointerException
- ifevents
is null.IllegalStateException
- if the producer was closed while queueing an event.
-
enqueueEvents
Enqueues a set ofEventData
into the buffer to be published to the Event Hub. If there is insufficient capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that all EventData in theevents
set have been enqueued. When this call returns, theevents
have been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.- Parameters:
events
- The set of events to be enqueued into the buffer and, later, published.options
- The set of options to apply when publishing this event.- Returns:
- The total number of events that are currently buffered and waiting to be published, across all partitions.
- Throws:
NullPointerException
- ifeventData
oroptions
is null.IllegalArgumentException
- ifgetPartitionId
is set and is not valid.IllegalStateException
- if the producer was closed while queueing an event.
-
flush
public void flush()Attempts to publish all events in the buffer immediately. This may result in multiple batches being published, the outcome of each of which will be individually reported by theEventHubBufferedProducerClientBuilder.onSendBatchFailed(Consumer)
andEventHubBufferedProducerClientBuilder.onSendBatchSucceeded(Consumer)
handlers. Upon completion of this method, the buffer will be empty. -
close
public void close()Disposes of the producer and all its resources.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-