EventHubClient Interface
public interface EventHubClient
Anchor class - all EventHub client operations STARTS here.
Field Summary
| Modifier and Type | Field and Description |
|---|---|
| static final String | DEFAULT_CONSUMER_GROUP_NAME |
Method Summary
Field Details
DEFAULT_CONSUMER_GROUP_NAME
public static final String DEFAULT_CONSUMER_GROUP_NAME
Method Details
close
public abstract CompletableFuture
closeSync
createBatch
public default EventDataBatch createBatch()
Creates an Empty Collection of EventData. The same partitionKey must be used while sending these events using send(EventDataBatch eventDatas).
Returns:
Throws:
createBatch
public abstract EventDataBatch createBatch(BatchOptions options)
Creates an Empty Collection of EventData. The same partitionKey must be used while sending these events using send(EventDataBatch eventDatas).
Parameters:
Returns:
Throws:
createEpochReceiver
public abstract CompletableFuture
Create a Epoch based EventHub receiver with given partition id and start receiving from the beginning of the partition stream. The receiver is created for a specific EventHub Partition from the specific consumer group.
It is important to pay attention to the following when creating epoch based receiver:
- Ownership enforcement - Once you created an epoch based receiver, you cannot create a non-epoch receiver to the same consumerGroup-Partition combo until all receivers to the combo are closed.
- Ownership stealing - If a receiver with higher epoch value is created for a consumerGroup-Partition combo, any older epoch receiver to that combo will be force closed.
- Any receiver closed due to lost of ownership to a consumerGroup-Partition combo will get ReceiverDisconnectedException for all operations from that receiver.
Parameters:
Returns:
Throws:
createEpochReceiver
public abstract CompletableFuture
Create a Epoch based EventHub receiver with given partition id and start receiving from the beginning of the partition stream. The receiver is created for a specific EventHub Partition from the specific consumer group.
It is important to pay attention to the following when creating epoch based receiver:
- Ownership enforcement - Once you created an epoch based receiver, you cannot create a non-epoch receiver to the same consumerGroup-Partition combo until all receivers to the combo are closed.
- Ownership stealing - If a receiver with higher epoch value is created for a consumerGroup-Partition combo, any older epoch receiver to that combo will be force closed.
- Any receiver closed due to lost of ownership to a consumerGroup-Partition combo will get ReceiverDisconnectedException for all operations from that receiver.
Parameters:
Returns:
Throws:
createEpochReceiverSync
public default PartitionReceiver createEpochReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch)
Synchronous version of createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch).
Parameters:
Returns:
Throws:
createEpochReceiverSync
public default PartitionReceiver createEpochReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch, ReceiverOptions receiverOptions)
Synchronous version of createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch).
Parameters:
Returns:
Throws:
createFromConnectionString
public static CompletableFuture
Factory method to create an instance of EventHubClient using the supplied connectionString. In a normal scenario (when re-direct is not enabled) - one EventHubClient instance maps to one Connection to the Azure ServiceBus EventHubs service.
The EventHubClient created from this method creates a Sender instance internally, which is used by the send(EventData data) methods.
Parameters:
Returns:
Throws:
createFromConnectionString
public static CompletableFuture
Factory method to create an instance of EventHubClient using the supplied connectionString. One EventHubClient instance maps to one connection to the Event Hubs service.
The EventHubClient created from this method creates a Sender instance internally, which is used by the send(EventData data) methods.
Parameters:
null or
SYSTEM_DEFAULTS if the system configured proxy settings should be used.
Returns:
Throws:
createFromConnectionString
public static CompletableFuture
Factory method to create an instance of EventHubClient using the supplied connectionString. One EventHubClient instance maps to one connection to the Event Hubs service.
The EventHubClient created from this method creates a Sender instance internally, which is used by the send(EventData data) methods.
Parameters:
null or
SYSTEM_DEFAULTS if the system configured proxy settings should be used.
Returns:
Throws:
createFromConnectionString
public static CompletableFuture
Factory method to create an instance of EventHubClient using the supplied connectionString. In a normal scenario (when re-direct is not enabled) - one EventHubClient instance maps to one Connection to the Azure ServiceBus EventHubs service.
The EventHubClient created from this method creates a Sender instance internally, which is used by the send(EventData data) methods.
Parameters:
Returns:
Throws:
createFromConnectionStringSync
public static EventHubClient createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor)
Synchronous version of createFromConnectionString(String connectionString, ScheduledExecutorService executor).
Parameters:
Returns:
Throws:
createFromConnectionStringSync
public static EventHubClient createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration configuration)
Synchronous version of createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration).
Parameters:
null or
SYSTEM_DEFAULTS if the system configured proxy settings should be used.
Returns:
Throws:
createFromConnectionStringSync
public static EventHubClient createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration configuration, Duration maximumSilentTime)
Synchronous version of createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration, Duration maximumSilentTime).
Parameters:
null or
SYSTEM_DEFAULTS if the system configured proxy settings should be used.
Returns:
Throws:
createFromConnectionStringSync
public static EventHubClient createFromConnectionStringSync(String connectionString, ScheduledExecutorService executor)
Synchronous version of createFromConnectionString(String connectionString, ScheduledExecutorService executor).
Parameters:
Returns:
Throws:
createPartitionSender
public abstract CompletableFuture
Create a PartitionSender which can publish EventData's directly to a specific EventHub partition (sender type iii. in the below list).
There are 3 patterns/ways to send to EventHubs:
i. or
ii. or
iii. or
Parameters:
Returns:
Throws:
createPartitionSenderSync
public default PartitionSender createPartitionSenderSync(String partitionId)
Synchronous version of createPartitionSender(String partitionId).
Parameters:
Returns:
Throws:
createReceiver
public abstract CompletableFuture
Create the EventHub receiver with given partition id and start receiving from the specified starting offset. The receiver is created for a specific EventHub Partition from the specific consumer group.
Parameters:
Returns:
Throws:
createReceiver
public abstract CompletableFuture
Create the EventHub receiver with given partition id and start receiving from the specified starting offset. The receiver is created for a specific EventHub Partition from the specific consumer group.
Parameters:
Returns:
Throws:
createReceiverSync
public default PartitionReceiver createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition)
Synchronous version of createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition).
Parameters:
Returns:
Throws:
createReceiverSync
public default PartitionReceiver createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, ReceiverOptions receiverOptions)
Synchronous version of createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition).
Parameters:
Returns:
Throws:
createWithAzureActiveDirectory
public static CompletableFuture
Factory method to create an instance of EventHubClient using the supplied namespace endpoint address, eventhub name and authentication mechanism. In a normal scenario (when re-direct is not enabled) - one EventHubClient instance maps to one Connection to the Azure ServiceBus EventHubs service.
The EventHubClient created from this method creates a Sender instance internally, which is used by the send(EventData data) methods.
Parameters:
Returns:
Throws:
createWithTokenProvider
public static CompletableFuture
Factory method to create an instance of EventHubClient using the supplied namespace endpoint address, eventhub name and authentication mechanism. In a normal scenario (when re-direct is not enabled) - one EventHubClient instance maps to one Connection to the Azure ServiceBus EventHubs service.
The EventHubClient created from this method creates a Sender instance internally, which is used by the send(EventData data) methods.
Parameters:
Returns:
Throws:
getEventHubName
public abstract String getEventHubName()
Returns:
getPartitionRuntimeInformation
public abstract CompletableFuture
Retrieves dynamic information about a partition of an event hub (see PartitionRuntimeInformation for details. Retries until it reaches the operation timeout, then either rethrows the last error if available or returns null to indicate timeout.
Parameters:
Returns:
getRuntimeInformation
public abstract CompletableFuture
Retrieves general information about an event hub (see EventHubRuntimeInformation for details). Retries until it reaches the operation timeout, then either rethrows the last error if available or returns null to indicate timeout.
Returns:
send
public abstract CompletableFuture
Send EventData to EventHub. The sent EventData will land on any arbitrarily chosen EventHubs partition.
There are 3 ways to send to EventHubs, each exposed as a method (along with its sendBatch overload):
- send(EventData data), send(Iterable<EventData> eventDatas), or send(EventDataBatch eventDatas)
- send(EventData eventData, String partitionKey) or send(Iterable<EventData> eventDatas, String partitionKey)
- send(EventData data), send(Iterable<EventData> eventDatas), or send(EventDataBatch eventDatas)
Use this method to Send, if:
a) the send() operation should be highly available and
b) the data needs to be evenly distributed among all partitions; exception being, when a subset of partitions are unavailable
send(EventData data) send's the EventData to a Service Gateway, which in-turn will forward the EventData to one of the EventHubs' partitions. Here's the message forwarding algorithm:
i. Forward the 's to EventHub partitions, by equally distributing the data among all partitions (ex: Round-robin the 's to all EventHubs' partitions)
ii. If one of the EventHub partitions is unavailable for a moment, the Service Gateway will automatically detect it and forward the message to another available partition - making the Send operation highly-available.
Parameters:
Returns:
send
public abstract CompletableFuture
Send an 'EventData with a partitionKey' to EventHub. All EventData's with a partitionKey are guaranteed to land on the same partition. This send pattern emphasize data correlation over general availability and latency.
There are 3 ways to send to EventHubs, each exposed as a method (along with its sendBatch overload):
i. or
ii. or
iii. or
Use this type of Send, if:
i. There is a need for correlation of events based on Sender instance; The sender can generate a UniqueId and set it as partitionKey - which on the received Message can be used for correlation
ii. The client wants to take control of distribution of data across partitions.
Multiple PartitionKey's could be mapped to one Partition. EventHubs service uses a proprietary Hash algorithm to map the PartitionKey to a PartitionId. Using this type of Send (Sending using a specific partitionKey), could sometimes result in partitions which are not evenly distributed.
Parameters:
Returns:
send
public abstract CompletableFuture
Send EventDataBatch to EventHub. The sent EventDataBatch will land according the partition key set in the EventDataBatch. If a partition key is not set, then we will Round-robin the EventData's to all EventHubs' partitions.
Parameters:
Returns:
send
public abstract CompletableFuture
Send a batch of EventData to EventHub. The sent EventData will land on any arbitrarily chosen EventHubs partition. This is the most recommended way to Send to EventHubs.
There are 3 ways to send to EventHubs, to understand this particular type of Send refer to the overload send(EventData data), which is used to send single EventData. Use this overload versus send(EventData data), if you need to send a batch of EventData.
Sending a batch of EventData's is useful in the following cases:
i. Efficient send - sending a batch of maximizes the overall throughput by optimally using the number of sessions created to EventHubs' service.
ii. Send multiple 's in a Transaction. To achieve ACID properties, the Gateway Service will forward all 's in the batch to a single EventHubs' partition.
Sample code (sample uses sync version of the api but concept are identical):
Gson gson = new GsonBuilder().create();
EventHubClient client = EventHubClient.createSync("__connection__");
while (true)
{
LinkedList events = new LinkedList();}
for (int count = 1; count < 11; count++)
{
PayloadEvent payload = new PayloadEvent(count);
byte[] payloadBytes = gson.toJson(payload).getBytes(Charset.defaultCharset());
EventData sendEvent = new EventData(payloadBytes);
sendEvent.getProperties().put("from", "javaClient");
events.add(sendEvent);
}
client.sendSync(events);
System.out.println(String.format("Sent Batch... Size: %s", events.size()));
}
for Exceptions refer to sendSync(Iterable<EventData> eventDatas)
Parameters:
Returns:
send
public abstract CompletableFuture
Send a 'batch of EventData with the same partitionKey' to EventHub. All EventData's with a partitionKey are guaranteed to land on the same partition. Multiple PartitionKey's will be mapped to one Partition.
There are 3 ways to send to EventHubs, to understand this particular type of Send refer to the overload send(EventData eventData, String partitionKey), which is the same type of Send and is used to send single EventData.
Sending a batch of EventData's is useful in the following cases:
i. Efficient send - sending a batch of maximizes the overall throughput by optimally using the number of sessions created to EventHubs service.
ii. Send multiple events in One Transaction. This is the reason why all events sent in a batch needs to have same partitionKey (so that they are sent to one partition only).
Parameters:
Returns:
sendSync
public default void sendSync(EventData data)
Synchronous version of send(EventData data).
Parameters:
Throws:
sendSync
public default void sendSync(EventData eventData, String partitionKey)
Synchronous version of send(EventData eventData, String partitionKey).
Parameters:
Throws:
sendSync
public default void sendSync(EventDataBatch eventDatas)
Synchronous version of send(EventDataBatch eventDatas).
Parameters:
Throws:
sendSync
public default void sendSync(Iterable
Synchronous version of send(Iterable<EventData> eventDatas).
Parameters:
Throws:
sendSync
public default void sendSync(Iterable
Synchronous version of send(Iterable<EventData> eventDatas, String partitionKey).
Parameters:
Throws:
Applies to
Azure SDK for Java
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for