Package com.microsoft.azure.eventhubs

Interface EventHubClient

All Known Implementing Classes:

EventHubClientImpl

public interface EventHubClient

Anchor class - all EventHub client operations STARTS here.

See Also:

createFromConnectionString(String, ScheduledExecutorService)

Field Summary

Fields

Modifier and Type	Field	Description
static String	DEFAULT_CONSUMER_GROUP_NAME

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	close()
void	closeSync()
default EventDataBatch	createBatch()	Creates an Empty Collection of EventData.
EventDataBatch	createBatch(BatchOptions options)	Creates an Empty Collection of EventData.
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.
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, String, EventPosition, long).
default PartitionReceiver	createEpochReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, long epoch, ReceiverOptions receiverOptions)	Synchronous version of createEpochReceiver(String, String, EventPosition, long).
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, ScheduledExecutorService).
static EventHubClient	createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration configuration)	Synchronous version of createFromConnectionString(String, RetryPolicy, ScheduledExecutorService, ProxyConfiguration).
static EventHubClient	createFromConnectionStringSync(String connectionString, RetryPolicy retryPolicy, ScheduledExecutorService executor, ProxyConfiguration configuration, Duration maximumSilentTime)	Synchronous version of createFromConnectionString(String, RetryPolicy, ScheduledExecutorService, ProxyConfiguration, Duration).
static EventHubClient	createFromConnectionStringSync(String connectionString, ScheduledExecutorService executor)	Synchronous version of createFromConnectionString(String, ScheduledExecutorService).
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).
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.
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, String, EventPosition).
default PartitionReceiver	createReceiverSync(String consumerGroupName, String partitionId, EventPosition eventPosition, ReceiverOptions receiverOptions)	Synchronous version of createReceiver(String, String, 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.
String	getEventHubName()
CompletableFuture<PartitionRuntimeInformation>	getPartitionRuntimeInformation(String partitionId)	Retrieves dynamic information about a partition of an event hub (see PartitionRuntimeInformation for details.
CompletableFuture<EventHubRuntimeInformation>	getRuntimeInformation()	Retrieves general information about an event hub (see EventHubRuntimeInformation for details).
CompletableFuture<Void>	send(EventData data)	Send EventData to EventHub.
CompletableFuture<Void>	send(EventDataBatch eventDatas)	Send EventDataBatch to EventHub.
CompletableFuture<Void>	send(EventData eventData, String partitionKey)	Send an 'EventData with a partitionKey' to EventHub.
CompletableFuture<Void>	send(Iterable<EventData> eventDatas)	Send a batch of EventData to EventHub.
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).
default void	sendSync(EventDataBatch eventDatas)	Synchronous version of send(EventDataBatch).
default void	sendSync(EventData eventData, String partitionKey)	Synchronous version of send(EventData, String).
default void	sendSync(Iterable<EventData> eventDatas)	Synchronous version of send(Iterable).
default void	sendSync(Iterable<EventData> eventDatas, String partitionKey)	Synchronous version of send(Iterable, String).

Field Detail

DEFAULT_CONSUMER_GROUP_NAME

static final String DEFAULT_CONSUMER_GROUP_NAME

See Also:

Constant Field Values

Method Detail

createFromConnectionStringSync

static EventHubClient createFromConnectionStringSync(String connectionString,
                                                     ScheduledExecutorService executor)
                                              throws EventHubException,
                                                     IOException

Synchronous version of createFromConnectionString(String, ScheduledExecutorService).

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 the underlying Proton-J layer encounter network errors.

createFromConnectionStringSync

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

Synchronous version of createFromConnectionString(String, ScheduledExecutorService).

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 the underlying Proton-J layer encounter network errors.

createFromConnectionStringSync

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

Synchronous version of createFromConnectionString(String, RetryPolicy, ScheduledExecutorService, 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 ProxyConfiguration.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 the underlying Proton-J layer encounter network errors.

createFromConnectionStringSync

static EventHubClient createFromConnectionStringSync(String connectionString,
                                                     RetryPolicy retryPolicy,
                                                     ScheduledExecutorService executor,
                                                     ProxyConfiguration configuration,
                                                     Duration maximumSilentTime)
                                              throws EventHubException,
                                                     IOException

Synchronous version of createFromConnectionString(String, RetryPolicy, ScheduledExecutorService, ProxyConfiguration, Duration).

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 ProxyConfiguration.SYSTEM_DEFAULTS if the system configured proxy settings should be used.

maximumSilentTime - Use EventHubClientOptions.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 the underlying Proton-J layer encounter network errors.

createFromConnectionString

static CompletableFuture<EventHubClient> createFromConnectionString(String connectionString,
                                                                    ScheduledExecutorService executor)
                                                             throws IOException

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) 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<EventHubClient> which can be used to create Senders and Receivers to EventHub

Throws:

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

createFromConnectionString

static CompletableFuture<EventHubClient> createFromConnectionString(String connectionString,
                                                                    RetryPolicy retryPolicy,
                                                                    ScheduledExecutorService executor)
                                                             throws IOException

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) 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<EventHubClient> which can be used to create Senders and Receivers to EventHub

Throws:

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

createFromConnectionString

static CompletableFuture<EventHubClient> createFromConnectionString(String connectionString,
                                                                    RetryPolicy retryPolicy,
                                                                    ScheduledExecutorService executor,
                                                                    ProxyConfiguration proxyConfiguration)
                                                             throws IOException

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) 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 ProxyConfiguration.SYSTEM_DEFAULTS if the system configured proxy settings should be used.

Returns:

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

Throws:

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

createFromConnectionString

static CompletableFuture<EventHubClient> createFromConnectionString(String connectionString,
                                                                    RetryPolicy retryPolicy,
                                                                    ScheduledExecutorService executor,
                                                                    ProxyConfiguration proxyConfiguration,
                                                                    Duration maximumSilentTime)
                                                             throws IOException

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) 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 ProxyConfiguration.SYSTEM_DEFAULTS if the system configured proxy settings should be used.

maximumSilentTime - Use EventHubClientOptions.SILENT_OFF except on recommendation from the product group.

Returns:

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

Throws:

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

createWithAzureActiveDirectory

static CompletableFuture<EventHubClient> createWithAzureActiveDirectory(URI endpointAddress,
                                                                        String eventHubName,
                                                                        AzureActiveDirectoryTokenProvider.AuthenticationCallback authCallback,
                                                                        String authority,
                                                                        ScheduledExecutorService executor,
                                                                        EventHubClientOptions options)
                                                                 throws IOException

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

static CompletableFuture<EventHubClient> createWithTokenProvider(URI endpointAddress,
                                                                 String eventHubName,
                                                                 ITokenProvider tokenProvider,
                                                                 ScheduledExecutorService executor,
                                                                 EventHubClientOptions options)
                                                          throws IOException

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

String getEventHubName()

Returns:

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

createBatch

EventDataBatch createBatch(BatchOptions options)
                    throws EventHubException

Creates an Empty Collection of EventData. The same partitionKey must be used while sending these events using send(EventDataBatch).

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.

createBatch

default EventDataBatch createBatch()
                            throws EventHubException

Creates an Empty Collection of EventData. The same partitionKey must be used while sending these events using send(EventDataBatch).

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.

sendSync

default void sendSync(EventData data)
               throws EventHubException

Synchronous version of send(EventData).

Parameters:

data - the EventData to be sent.

Throws:

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

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

UnresolvedAddressException - if there are Client to Service network connectivity issues, if the Azure DNS resolution of the ServiceBus Namespace fails (ex: namespace deleted etc.)

send

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

• send(EventData), send(Iterable), or send(EventDataBatch)
• send(EventData, String) or send(Iterable, String)
• PartitionSender.send(EventData), PartitionSender.send(Iterable), or PartitionSender.send(EventDataBatch)

Use this method to Send, if:

 a)  the send(EventData) 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) 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 EventData's to EventHub partitions, by equally distributing the data among all partitions (ex: Round-robin the EventData'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..

See Also:

send(EventData, String), PartitionSender.send(EventData)

sendSync

default void sendSync(Iterable<EventData> eventDatas)
               throws EventHubException

Synchronous version of send(Iterable).

Parameters:

eventDatas - batch of events to send to EventHub

Throws:

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

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

UnresolvedAddressException - if there are Client to Service network connectivity issues, if the Azure DNS resolution of the ServiceBus Namespace fails (ex: namespace deleted etc.)

send

CompletableFuture<Void> send(Iterable<EventData> 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), which is used to send single EventData. Use this overload versus send(EventData), 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 EventData maximizes the overall throughput by optimally using the number of sessions created to EventHubs' service.
 ii.  Send multiple EventData's in a Transaction. To achieve ACID properties, the Gateway Service will forward all EventData'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<EventData> events = new LinkedList<EventData>();}
     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)

Parameters:

eventDatas - batch of events to send to EventHub

Returns:

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

See Also:

send(EventData, String), PartitionSender.send(EventData)

sendSync

default void sendSync(EventDataBatch eventDatas)
               throws EventHubException

Synchronous version of send(EventDataBatch).

Parameters:

eventDatas - EventDataBatch to send to EventHub

Throws:

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

send

CompletableFuture<Void> 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

See Also:

send(Iterable), EventDataBatch

sendSync

default void sendSync(EventData eventData,
                      String partitionKey)
               throws EventHubException

Synchronous version of send(EventData, String).

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 EventData.SystemProperties.getPartitionKey()

Throws:

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

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

send

CompletableFuture<Void> 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.   send(EventData) or send(Iterable)
 ii.  send(EventData, String) or send(Iterable, String)
 iii. PartitionSender.send(EventData) or PartitionSender.send(Iterable)
 

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 EventData.SystemProperties.getPartitionKey()

Returns:

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

See Also:

send(EventData), PartitionSender.send(EventData)

sendSync

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

Synchronous version of send(Iterable, String).

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 EventData.SystemProperties.getPartitionKey()

Throws:

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

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

UnresolvedAddressException - if there are Client to Service network connectivity issues, if the Azure DNS resolution of the ServiceBus Namespace fails (ex: namespace deleted etc.)

send

CompletableFuture<Void> send(Iterable<EventData> 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, String), 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 EventData 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 EventData.SystemProperties.getPartitionKey()

Returns:

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

See Also:

send(EventData), PartitionSender.send(EventData)

createPartitionSenderSync

default PartitionSender createPartitionSenderSync(String partitionId)
                                           throws EventHubException,
                                                  IllegalArgumentException

Synchronous version of createPartitionSender(String).

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

createPartitionSender

CompletableFuture<PartitionSender> createPartitionSender(String partitionId)
                                                  throws EventHubException

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.   send(EventData) or send(Iterable)
 ii.  send(EventData, String) or send(Iterable, String)
 iii. PartitionSender.send(EventData) or PartitionSender.send(Iterable)
 

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.

See Also:

PartitionSender

createReceiverSync

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

Synchronous version of createReceiver(String, String, 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.

createReceiver

CompletableFuture<PartitionReceiver> createReceiver(String consumerGroupName,
                                                    String partitionId,
                                                    EventPosition eventPosition)
                                             throws EventHubException

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.

See Also:

PartitionReceiver

createReceiverSync

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

Synchronous version of createReceiver(String, String, 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.

createReceiver

CompletableFuture<PartitionReceiver> createReceiver(String consumerGroupName,
                                                    String partitionId,
                                                    EventPosition eventPosition,
                                                    ReceiverOptions receiverOptions)
                                             throws EventHubException

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.

See Also:

PartitionReceiver

createEpochReceiverSync

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

Synchronous version of createEpochReceiver(String, String, EventPosition, long).

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.

createEpochReceiver

CompletableFuture<PartitionReceiver> createEpochReceiver(String consumerGroupName,
                                                         String partitionId,
                                                         EventPosition eventPosition,
                                                         long epoch)
                                                  throws EventHubException

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.

See Also:

PartitionReceiver, ReceiverDisconnectedException

createEpochReceiverSync

default PartitionReceiver createEpochReceiverSync(String consumerGroupName,
                                                  String partitionId,
                                                  EventPosition eventPosition,
                                                  long epoch,
                                                  ReceiverOptions receiverOptions)
                                           throws EventHubException

Synchronous version of createEpochReceiver(String, String, EventPosition, long).

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.

createEpochReceiver

CompletableFuture<PartitionReceiver> createEpochReceiver(String consumerGroupName,
                                                         String partitionId,
                                                         EventPosition eventPosition,
                                                         long epoch,
                                                         ReceiverOptions receiverOptions)
                                                  throws EventHubException

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.

See Also:

PartitionReceiver, ReceiverDisconnectedException

getRuntimeInformation

CompletableFuture<EventHubRuntimeInformation> 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.

getPartitionRuntimeInformation

CompletableFuture<PartitionRuntimeInformation> 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.

close

CompletableFuture<Void> close()

closeSync

void closeSync()
        throws EventHubException

Throws:

EventHubException