EventHubClient.send Method

Definition

Overloads

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

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.

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

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

send(EventData data)

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

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
EventData

the EventData to be sent.

Returns

java.util.concurrent.CompletableFuture<java.lang.Void>

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

send(EventData eventData, String partitionKey)

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

the EventData to be sent.

partitionKey
java.lang.String

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

java.util.concurrent.CompletableFuture<java.lang.Void>

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

send(EventDataBatch eventDatas)

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

EventDataBatch to send to EventHub

Returns

java.util.concurrent.CompletableFuture<java.lang.Void>

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

send(Iterable<EventData> eventDatas)

public abstract 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 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
java.lang.Iterable<EventData>

batch of events to send to EventHub

Returns

java.util.concurrent.CompletableFuture<java.lang.Void>

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

send(Iterable<EventData> eventDatas, String partitionKey)

public abstract 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 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
java.lang.Iterable<EventData>

the batch of events to send to EventHub

partitionKey
java.lang.String

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

java.util.concurrent.CompletableFuture<java.lang.Void>

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

Applies to