EventHubProducerClient Class

A synchronous producer responsible for transmitting EventData to a specific Event Hub, grouped together in batches. Depending on the CreateBatchOptions specified when creating an EventDataBatch, the events may be automatically routed to an available partition or specific to a partition. More information and specific recommendations for strategies to use when publishing events is in: Distribute events to partitions

Allowing automatic routing of partitions is recommended when:

• The sending of events needs to be highly available.
• The event data should be evenly distributed among all available partitions.

If no partition id is specified, the following rules are used for automatically selecting one:

1. Distribute the events equally amongst all available partitions using a round-robin approach.
2. If a partition becomes unavailable, the Event Hubs service will automatically detect it and forward the message to another available partition.

The examples shown in this document use a credential object named DefaultAzureCredential for authentication, which is appropriate for most scenarios, including local development and production environments. Additionally, we recommend using managed identity for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the Azure Identity documentation".

Sample: Construct a EventHubProducerClient

The following code sample demonstrates the creation of the synchronous client EventHubProducerClient. The fullyQualifiedNamespace is the Event Hubs Namespace's host name. It is listed under the "Essentials" panel after navigating to the Event Hubs Namespace via Azure Portal.

TokenCredential credential = new DefaultAzureCredentialBuilder().build();

 // "<<fully-qualified-namespace>>" will look similar to "{your-namespace}.servicebus.windows.net"
 // "<<event-hub-name>>" will be the name of the Event Hub instance you created inside the Event Hubs namespace.
 EventHubProducerClient producer = new EventHubClientBuilder()
     .credential("<<fully-qualified-namespace>>", "<<event-hub-name>>",
         credential)
     .buildProducerClient();

Sample: Create a producer and publish events to any partition

The following code sample demonstrates publishing events and allowing the service to distribute the events round-robin between all partitions.

TokenCredential credential = new DefaultAzureCredentialBuilder().build();

 EventHubProducerClient producer = new EventHubClientBuilder()
     .credential("<<fully-qualified-namespace>>", "<<event-hub-name>>",
         credential)
     .buildProducerClient();

 List<EventData> allEvents = Arrays.asList(new EventData("Foo"), new EventData("Bar"));
 EventDataBatch eventDataBatch = producer.createBatch();

 for (EventData eventData : allEvents) {
     if (!eventDataBatch.tryAdd(eventData)) {
         producer.send(eventDataBatch);
         eventDataBatch = producer.createBatch();

         // Try to add that event that couldn't fit before.
         if (!eventDataBatch.tryAdd(eventData)) {
             throw new IllegalArgumentException("Event is too large for an empty batch. Max size: "
                 + eventDataBatch.getMaxSizeInBytes());
         }
     }
 }

 // send the last batch of remaining events
 if (eventDataBatch.getCount() > 0) {
     producer.send(eventDataBatch);
 }

 // Clients are expected to be long-lived objects.
 // Dispose of the producer to close any underlying resources when we are finished with it.
 producer.close();

Sample: Publish events to partition "0"

The following code sample demonstrates publishing events to a specific partition. In the scenario below, all events are sent to partition "0".

TokenCredential credential = new DefaultAzureCredentialBuilder().build();

 EventHubProducerClient producer = new EventHubClientBuilder()
     .credential("<<fully-qualified-namespace>>", "<<event-hub-name>>",
         credential)
     .buildProducerClient();

 // Creating a batch with partitionId set will route all events in that batch to partition `0`.
 CreateBatchOptions options = new CreateBatchOptions().setPartitionId("0");
 EventDataBatch batch = producer.createBatch(options);

 // Add events to batch and when you want to send the batch, send it using the producer.
 producer.send(batch);

Sample: Publish events to the same partition, grouped together using partition key

The sample code below uses setPartitionKey(String partitionKey) when creating the EventDataBatch. All events added to this batch will be published to the same partition. In general, events with the same partitionKey end up in the same partition.

List<EventData> events = Arrays.asList(new EventData("sourdough"), new EventData("rye"),
     new EventData("wheat"));

 // Creating a batch with partitionKey set will tell the service to hash the partitionKey and decide which
 // partition to send the events to. Events with the same partitionKey are always routed to the same partition.
 CreateBatchOptions options = new CreateBatchOptions().setPartitionKey("bread");
 EventDataBatch batch = producer.createBatch(options);

 events.forEach(event -> batch.tryAdd(event));
 producer.send(batch);

Sample: Publish events using a size-limited EventDataBatch

The sample code below uses setMaximumSizeInBytes(int maximumSizeInBytes) when creating the EventDataBatch. In the example, it limits the size of the batch to 256 bytes. This is useful for scenarios where there are constraints like network throughput, memory, etc.

List<EventData> telemetryEvents = Arrays.asList(firstEvent, secondEvent, thirdEvent);

 // Setting `setMaximumSizeInBytes` when creating a batch, limits the size of that batch.
 // In this case, all the batches created with these options are limited to 256 bytes.
 CreateBatchOptions options = new CreateBatchOptions().setMaximumSizeInBytes(256);

 EventDataBatch currentBatch = producer.createBatch(options);

 // For each telemetry event, we try to add it to the current batch.
 // When the batch is full, send it then create another batch to add more events to.
 for (EventData event : telemetryEvents) {
     if (!currentBatch.tryAdd(event)) {
         producer.send(currentBatch);
         currentBatch = producer.createBatch(options);

         // Add the event we couldn't before.
         if (!currentBatch.tryAdd(event)) {
             throw new IllegalArgumentException("Event is too large for an empty batch.");
         }
     }
 }