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

Modifier and Type Method and Description
abstract

CompletableFuture<Void>

close()
abstract void closeSync()
default EventDataBatch createBatch()

Creates an Empty Collection of EventData.

abstract EventDataBatch createBatch(BatchOptions options)

Creates an Empty Collection of EventData.

abstract

CompletableFuture<PartitionReceiver>

createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch)

Create a Epoch based EventHub receiver with given partition id and start receiving from the beginning of the partition stream.

abstract

CompletableFuture<PartitionReceiver>

createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch, ReceiverOptions receiverOptions)

Create a Epoch based EventHub receiver with given partition id and start receiving from the beginning of the partition stream.

default PartitionReceiver createEpochReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch)

Synchronous version of createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch).

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).

static

CompletableFuture<EventHubClient>

createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor)

Factory method to create an instance of EventHubClient using the supplied connectionString.

static

CompletableFuture<EventHubClient>

createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration)

Factory method to create an instance of EventHubClient using the supplied connectionString.

static

CompletableFuture<EventHubClient>

createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration, Duration maximumSilentTime)

Factory method to create an instance of EventHubClient using the supplied connectionString.

static

CompletableFuture<EventHubClient>

createFromConnectionString(String connectionString, ScheduledExecutorService executor)

Factory method to create an instance of EventHubClient using the supplied connectionString.

static EventHubClient createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor)

Synchronous version of createFromConnectionString(String connectionString, ScheduledExecutorService executor).

static EventHubClient createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration configuration)

Synchronous version of createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration).

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).

static EventHubClient createFromConnectionStringSync(String connectionString, ScheduledExecutorService executor)

Synchronous version of createFromConnectionString(String connectionString, ScheduledExecutorService executor).

abstract

CompletableFuture<PartitionSender>

createPartitionSender(String partitionId)

Create a PartitionSender which can publish EventData's directly to a specific EventHub partition (sender type iii.

default PartitionSender createPartitionSenderSync(String partitionId)

Synchronous version of createPartitionSender(String partitionId).

abstract

CompletableFuture<PartitionReceiver>

createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition)

Create the EventHub receiver with given partition id and start receiving from the specified starting offset.

abstract

CompletableFuture<PartitionReceiver>

createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, ReceiverOptions receiverOptions)

Create the EventHub receiver with given partition id and start receiving from the specified starting offset.

default PartitionReceiver createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition)

Synchronous version of createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition).

default PartitionReceiver createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, ReceiverOptions receiverOptions)

Synchronous version of createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition).

static

CompletableFuture<EventHubClient>

createWithAzureActiveDirectory(URI endpointAddress, String eventHubName, AzureActiveDirectoryTokenProvider.AuthenticationCallback authCallback, String authority, ScheduledExecutorService executor, EventHubClientOptions options)

Factory method to create an instance of EventHubClient using the supplied namespace endpoint address, eventhub name and authentication mechanism.

static

CompletableFuture<EventHubClient>

createWithTokenProvider(URI endpointAddress, String eventHubName, ITokenProvider tokenProvider, ScheduledExecutorService executor, EventHubClientOptions options)

Factory method to create an instance of EventHubClient using the supplied namespace endpoint address, eventhub name and authentication mechanism.

abstract

String

getEventHubName()
abstract

CompletableFuture<PartitionRuntimeInformation>

getPartitionRuntimeInformation(String partitionId)

Retrieves dynamic information about a partition of an event hub (see PartitionRuntimeInformation for details.

abstract

CompletableFuture<EventHubRuntimeInformation>

getRuntimeInformation()

Retrieves general information about an event hub (see EventHubRuntimeInformation for details).

abstract

CompletableFuture<Void>

send(EventData data)

Send EventData to EventHub.

abstract

CompletableFuture<Void>

send(EventData eventData, String partitionKey)

Send an 'EventData with a partitionKey' to EventHub.

abstract

CompletableFuture<Void>

send(EventDataBatch eventDatas)

Send EventDataBatch to EventHub.

abstract

CompletableFuture<Void>

send(Iterable<EventData> eventDatas)

Send a batch of EventData to EventHub.

abstract

CompletableFuture<Void>

send(Iterable<EventData> eventDatas, String partitionKey)

Send a 'batch of EventData with the same partitionKey' to EventHub.

default void sendSync(EventData data)

Synchronous version of send(EventData data).

default void sendSync(EventData eventData, String partitionKey)

Synchronous version of send(EventData eventData, String partitionKey).

default void sendSync(EventDataBatch eventDatas)

Synchronous version of send(EventDataBatch eventDatas).

default void sendSync(Iterable<EventData> eventDatas)

Synchronous version of send(Iterable<EventData> eventDatas).

default void sendSync(Iterable<EventData> eventDatas, String partitionKey)

Synchronous version of send(Iterable<EventData> eventDatas, String partitionKey).

Field Details

DEFAULT_CONSUMER_GROUP_NAME

public static final String DEFAULT_CONSUMER_GROUP_NAME

Method Details

close

public abstract CompletableFuture close()

closeSync

public abstract void closeSync()

Throws:

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:

the empty EventDataBatch, after negotiating maximum message size with EventHubs service

Throws:

EventHubException - if the Microsoft Azure Event Hubs service encountered problems during the operation.

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:

options - see BatchOptions for more details

Returns:

the empty EventDataBatch, after negotiating maximum message size with EventHubs service

Throws:

EventHubException - if the Microsoft Azure Event Hubs service encountered problems during the operation.

createEpochReceiver

public abstract CompletableFuture createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch)

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:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition
epoch - an unique identifier (epoch value) that the service uses, to enforce partition/lease ownership.

Returns:

a CompletableFuture that would result in a PartitionReceiver when it is completed.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

createEpochReceiver

public abstract CompletableFuture createEpochReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch, ReceiverOptions receiverOptions)

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:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition
epoch - an unique identifier (epoch value) that the service uses, to enforce partition/lease ownership.
receiverOptions - the set of options to enable on the event hubs receiver

Returns:

a CompletableFuture that would result in a PartitionReceiver when it is completed.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

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:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition
epoch - an unique identifier (epoch value) that the service uses, to enforce partition/lease ownership.

Returns:

PartitionReceiver instance which can be used for receiving EventData.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

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:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition
epoch - an unique identifier (epoch value) that the service uses, to enforce partition/lease ownership.
receiverOptions - the set of options to enable on the event hubs receiver

Returns:

PartitionReceiver instance which can be used for receiving EventData.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

createFromConnectionString

public static CompletableFuture createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor)

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:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
retryPolicy - A custom RetryPolicy to be used when communicating with EventHub.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.

Returns:

CompletableFuture which can be used to create Senders and Receivers to EventHub

Throws:

IOException

- If the underlying Proton-J layer encounter network errors.

createFromConnectionString

public static CompletableFuture createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration)

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:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
retryPolicy - A custom RetryPolicy to be used when communicating with EventHub.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.
proxyConfiguration - The proxy configuration for this EventHubClient connection; null or SYSTEM_DEFAULTS if the system configured proxy settings should be used.

Returns:

CompletableFuture which can be used to create Senders and Receivers to EventHub.

Throws:

IOException

- If the underlying Proton-J layer encounter network errors.

createFromConnectionString

public static CompletableFuture createFromConnectionString(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration proxyConfiguration, Duration maximumSilentTime)

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:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
retryPolicy - A custom RetryPolicy to be used when communicating with EventHub.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.
proxyConfiguration - The proxy configuration for this EventHubClient connection; null or SYSTEM_DEFAULTS if the system configured proxy settings should be used.
maximumSilentTime - Use SILENT_OFF except on recommendation from the product group.

Returns:

CompletableFuture which can be used to create Senders and Receivers to EventHub.

Throws:

IOException

- If the underlying Proton-J layer encounter network errors.

createFromConnectionString

public static CompletableFuture createFromConnectionString(String connectionString, ScheduledExecutorService executor)

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:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.

Returns:

CompletableFuture which can be used to create Senders and Receivers to EventHub

Throws:

IOException

- If the underlying Proton-J layer encounter network errors.

createFromConnectionStringSync

public static EventHubClient createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor)

Synchronous version of createFromConnectionString(String connectionString, ScheduledExecutorService executor).

Parameters:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
retryPolicy - A custom RetryPolicy to be used when communicating with EventHub.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.

Returns:

EventHubClient which can be used to create Senders and Receivers to EventHub

Throws:

EventHubException - If Service Bus service encountered problems during connection creation.

IOException

- If Service Bus service encountered problems during connection creation.

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:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
retryPolicy - A custom RetryPolicy to be used when communicating with EventHub.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.
configuration - The proxy configuration for this EventHubClient connection; null or SYSTEM_DEFAULTS if the system configured proxy settings should be used.

Returns:

EventHubClient which can be used to create Senders and Receivers to EventHub

Throws:

EventHubException - If Service Bus service encountered problems during connection creation.

IOException

- If Service Bus service encountered problems during connection creation.

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:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
retryPolicy - A custom RetryPolicy to be used when communicating with EventHub.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.
configuration - The proxy configuration for this EventHubClient connection; null or SYSTEM_DEFAULTS if the system configured proxy settings should be used.
maximumSilentTime - Use SILENT_OFF except on recommendation from the product group.

Returns:

EventHubClient which can be used to create Senders and Receivers to EventHub

Throws:

EventHubException - If Service Bus service encountered problems during connection creation.

IOException

- If Service Bus service encountered problems during connection creation.

createFromConnectionStringSync

public static EventHubClient createFromConnectionStringSync(String connectionString, ScheduledExecutorService executor)

Synchronous version of createFromConnectionString(String connectionString, ScheduledExecutorService executor).

Parameters:

connectionString - The connection string to be used. See ConnectionStringBuilder to construct a connectionString.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.

Returns:

EventHubClient which can be used to create Senders and Receivers to EventHub

Throws:

EventHubException - If Service Bus service encountered problems during connection creation.

IOException

- If Service Bus service encountered problems during connection creation.

createPartitionSender

public abstract CompletableFuture createPartitionSender(String partitionId)

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:

partitionId - partitionId of EventHub to send the EventData's to

Returns:

a CompletableFuture that would result in a PartitionSenderImpl when it is completed.

Throws:

EventHubException - if Service Bus service encountered problems during connection creation.

createPartitionSenderSync

public default PartitionSender createPartitionSenderSync(String partitionId)

Synchronous version of createPartitionSender(String partitionId).

Parameters:

partitionId - partitionId of EventHub to send the EventData's to

Returns:

PartitionSenderImpl which can be used to send events to a specific partition.

Throws:

EventHubException - if Service Bus service encountered problems during connection creation.

IllegalArgumentException

- if Service Bus service encountered problems during connection creation.

createReceiver

public abstract CompletableFuture createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition)

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:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition

Returns:

a CompletableFuture that would result in a PartitionReceiver instance when it is completed.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

createReceiver

public abstract CompletableFuture createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition, ReceiverOptions receiverOptions)

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:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition
receiverOptions - the set of options to enable on the event hubs receiver

Returns:

a CompletableFuture that would result in a PartitionReceiver instance when it is completed.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

createReceiverSync

public default PartitionReceiver createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition)

Synchronous version of createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition).

Parameters:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition

Returns:

PartitionReceiver instance which can be used for receiving EventData.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

createReceiverSync

public default PartitionReceiver createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, ReceiverOptions receiverOptions)

Synchronous version of createReceiver(String consumerGroupName, String partitionId, EventPosition eventPosition).

Parameters:

consumerGroupName - the consumer group name that this receiver should be grouped under.
partitionId - the partition Id that the receiver belongs to. All data received will be from this partition only.
eventPosition - the position to start receiving the events from. See EventPosition
receiverOptions - the set of options to enable on the event hubs receiver

Returns:

PartitionReceiver instance which can be used for receiving EventData.

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

createWithAzureActiveDirectory

public static CompletableFuture createWithAzureActiveDirectory(URI endpointAddress, String eventHubName, AzureActiveDirectoryTokenProvider.AuthenticationCallback authCallback, String authority, ScheduledExecutorService executor, EventHubClientOptions options)

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:

endpointAddress - namespace level endpoint. This needs to be in the format of scheme://fullyQualifiedServiceBusNamespaceEndpointName
eventHubName - EventHub name
authCallback - A callback which returns a JSON Web Token obtained from AAD.
authority - Address of the AAD authority to issue the token.
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.
options - Options EventHubClientOptions for creating the client. Uses all defaults if null.

Returns:

EventHubClient which can be used to create Senders and Receivers to EventHub

Throws:

IOException

- If the underlying Proton-J layer encounter network errors.

createWithTokenProvider

public static CompletableFuture createWithTokenProvider(URI endpointAddress, String eventHubName, ITokenProvider tokenProvider, ScheduledExecutorService executor, EventHubClientOptions options)

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:

endpointAddress - namespace level endpoint. This needs to be in the format of scheme://fullyQualifiedServiceBusNamespaceEndpointName
eventHubName - EventHub name
tokenProvider - The ITokenProvider implementation to be used to authenticate
executor - An ScheduledExecutorService to run all tasks performed by EventHubClient.
options - Options EventHubClientOptions for creating the client. Uses all defaults if null.

Returns:

EventHubClient which can be used to create Senders and Receivers to EventHub

Throws:

IOException

- If the underlying Proton-J layer encounter network errors.

getEventHubName

public abstract String getEventHubName()

Returns:

the name of the Event Hub this client is connected to.

getPartitionRuntimeInformation

public abstract CompletableFuture getPartitionRuntimeInformation(String partitionId)

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:

partitionId - Partition to get information about. Must be one of the partition ids returned by #getRuntimeInformation.

Returns:

CompletableFuture which returns an PartitionRuntimeInformation on success, or null on timeout.

getRuntimeInformation

public abstract CompletableFuture getRuntimeInformation()

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:

CompletableFuture which returns an EventHubRuntimeInformation on success, or null on timeout.

send

public abstract CompletableFuture send(EventData data)

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):

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:

data - the EventData to be sent.

Returns:

a CompletableFuture that can be completed when the send operations is done..

send

public abstract CompletableFuture send(EventData eventData, String partitionKey)

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:

eventData - the EventData to be sent.
partitionKey - the partitionKey will be hash'ed to determine the partitionId to send the eventData to. On the Received message this can be accessed at getPartitionKey()

Returns:

a CompletableFuture that can be completed when the send operations is done..

send

public abstract CompletableFuture send(EventDataBatch eventDatas)

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:

eventDatas - EventDataBatch to send to EventHub

Returns:

a CompleteableFuture that can be completed when the send operations are done

send

public abstract CompletableFuture send(Iterable eventDatas)

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:

eventDatas - batch of events to send to EventHub

Returns:

a CompletableFuture that can be completed when the send operations is done..

send

public abstract CompletableFuture send(Iterable eventDatas, String partitionKey)

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:

eventDatas - the batch of events to send to EventHub
partitionKey - the partitionKey will be hash'ed to determine the partitionId to send the eventData to. On the Received message this can be accessed at getPartitionKey()

Returns:

a CompletableFuture that can be completed when the send operations is done..

sendSync

public default void sendSync(EventData data)

Synchronous version of send(EventData data).

Parameters:

data - the EventData to be sent.

Throws:

EventHubException - if the total size of the EventData exceeds a predefined limit set by the service. Default is 256k bytes.

sendSync

public default void sendSync(EventData eventData, String partitionKey)

Synchronous version of send(EventData eventData, String partitionKey).

Parameters:

eventData - the EventData to be sent.
partitionKey - the partitionKey will be hash'ed to determine the partitionId to send the eventData to. On the Received message this can be accessed at getPartitionKey()

Throws:

EventHubException - if the total size of the EventData exceeds a pre-defined limit set by the service. Default is 256k bytes.

sendSync

public default void sendSync(EventDataBatch eventDatas)

Synchronous version of send(EventDataBatch eventDatas).

Parameters:

eventDatas - EventDataBatch to send to EventHub

Throws:

EventHubException - if Service Bus service encountered problems during the operation.

sendSync

public default void sendSync(Iterable eventDatas)

Synchronous version of send(Iterable<EventData> eventDatas).

Parameters:

eventDatas - batch of events to send to EventHub

Throws:

EventHubException - if the total size of the EventData exceeds a pre-defined limit set by the service. Default is 256k bytes.

sendSync

public default void sendSync(Iterable eventDatas, String partitionKey)

Synchronous version of send(Iterable<EventData> eventDatas, String partitionKey).

Parameters:

eventDatas - the batch of events to send to EventHub
partitionKey - the partitionKey will be hash'ed to determine the partitionId to send the eventData to. On the Received message this can be accessed at getPartitionKey()

Throws:

EventHubException - if the total size of the EventData exceeds a pre-defined limit set by the service. Default is 256k bytes.

Applies to