Package com.azure.messaging.eventhubs

Class EventHubClientBuilder

java.lang.Object
com.azure.messaging.eventhubs.EventHubClientBuilder
All Implemented Interfaces:
com.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>, com.azure.core.client.traits.AzureNamedKeyCredentialTrait<EventHubClientBuilder>, com.azure.core.client.traits.AzureSasCredentialTrait<EventHubClientBuilder>, com.azure.core.client.traits.ConfigurationTrait<EventHubClientBuilder>, com.azure.core.client.traits.ConnectionStringTrait<EventHubClientBuilder>, com.azure.core.client.traits.TokenCredentialTrait<EventHubClientBuilder>
public class EventHubClientBuilder extends Object implements com.azure.core.client.traits.TokenCredentialTrait<EventHubClientBuilder>, com.azure.core.client.traits.AzureNamedKeyCredentialTrait<EventHubClientBuilder>, com.azure.core.client.traits.ConnectionStringTrait<EventHubClientBuilder>, com.azure.core.client.traits.AzureSasCredentialTrait<EventHubClientBuilder>, com.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>, com.azure.core.client.traits.ConfigurationTrait<EventHubClientBuilder>
This class provides a fluent builder API to aid the instantiation of EventHubProducerAsyncClient, EventHubProducerClient, EventHubConsumerAsyncClient, and EventHubConsumerClient. Calling any of the .build*Client() methods will create an instance of the respective client.

Credentials are required to perform operations against Azure Event Hubs. They can be set by using one of the following methods:

In addition, the consumerGroup(String) is required when creating EventHubConsumerAsyncClient or EventHubConsumerClient.

The credential used in the following samples is DefaultAzureCredential for authentication. It 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 EventHubProducerAsyncClient

The following code sample demonstrates the creation of the asynchronous client EventHubProducerAsyncClient. 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. The credential used is DefaultAzureCredential because it combines commonly used credentials in deployment and development and chooses the credential to used based on its running environment.

 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.
 EventHubProducerAsyncClient producer = new EventHubClientBuilder()
     .credential("<<fully-qualified-namespace>>", "<<event-hub-name>>",
         credential)
     .buildAsyncProducerClient();

Sample: Construct a EventHubConsumerAsyncClient

The following code sample demonstrates the creation of the asynchronous client EventHubConsumerAsyncClient. 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. The consumerGroup is found by navigating to the Event Hub instance, and selecting "Consumer groups" under the "Entities" panel. The consumerGroup(String) is required for creating consumer clients. The credential used is DefaultAzureCredential because it combines commonly used credentials in deployment and development and chooses the credential to used based on its running environment.

 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.
 EventHubConsumerAsyncClient consumer = new EventHubClientBuilder()
     .credential("<<fully-qualified-namespace>>", "<<event-hub-name>>",
         credential)
     .consumerGroup(EventHubClientBuilder.DEFAULT_CONSUMER_GROUP_NAME)
     .buildAsyncConsumerClient();

Sample: Creating a client using web sockets and custom retry options

By default, the AMQP port 5671 is used, but clients can use web sockets, port 443. Customers can replace the default retry options with their own policy. The retry options are used when recovering from transient failures in the underlying AMQP connection and performing any operations that require a response from the service.

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

 AmqpRetryOptions customRetryOptions = new AmqpRetryOptions()
     .setMaxRetries(5)
     .setMode(AmqpRetryMode.FIXED)
     .setTryTimeout(Duration.ofSeconds(60));

 // "<<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)
     .transportType(AmqpTransportType.AMQP_WEB_SOCKETS)
     .buildProducerClient();

Sample: Creating producers and consumers that share the same connection

By default, a dedicated connection is created for each producer and consumer created from the builder. If users wish to use the same underlying connection, they can toggle shareConnection(). This underlying connection is closed when all clients created from this builder instance are disposed.

 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.
 EventHubClientBuilder builder = new EventHubClientBuilder()
     .credential("<<fully-qualified-namespace>>", "<<event-hub-name>>",
         credential)
     .shareConnection();

 // Both the producer and consumer created share the same underlying connection.
 EventHubProducerAsyncClient producer = builder.buildAsyncProducerClient();
 EventHubConsumerAsyncClient consumer = builder
     .consumerGroup("my-consumer-group")
     .buildAsyncConsumerClient();
See Also:

  • Field Details

    • DEFAULT_CONSUMER_GROUP_NAME

      public static final String DEFAULT_CONSUMER_GROUP_NAME
      The name of the default consumer group in the Event Hubs service.
      See Also:

  • Constructor Details

    • EventHubClientBuilder

      public EventHubClientBuilder()
      Creates a new instance with the default transport AmqpTransportType.AMQP and a non-shared connection. A non-shared connection means that a dedicated AMQP connection is created for every Event Hub consumer or producer created using the builder.

  • Method Details

    • clientOptions

      public EventHubClientBuilder clientOptions(com.azure.core.util.ClientOptions clientOptions)
      Sets the client options.
      Specified by:
      clientOptions in interface com.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
      Parameters:
      clientOptions - The client options.
      Returns:
      The updated EventHubClientBuilder object.

    • connectionString

      public EventHubClientBuilder connectionString(String connectionString)
      Sets the credential information given a connection string to the Event Hub instance or the Event Hubs namespace.

      If the connection string is copied from the Event Hubs namespace, it will likely not contain the name to the desired Event Hub, which is needed. In this case, the name can be added manually by adding "EntityPath=EVENT_HUB_NAME" to the end of the connection string. For example, "EntityPath=telemetry-hub".

      If you have defined a shared access policy directly on the Event Hub itself, then copying the connection string from that Event Hub will result in a connection string that contains the name.

      Specified by:
      connectionString in interface com.azure.core.client.traits.ConnectionStringTrait<EventHubClientBuilder>
      Parameters:
      connectionString - The connection string to use for connecting to the Event Hub instance or Event Hubs instance. It is expected that the Event Hub name and the shared access key properties are contained in this connection string.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if connectionString is null or empty. If fullyQualifiedNamespace in the connection string is null.
      NullPointerException - if a credential could not be extracted
      com.azure.core.exception.AzureException - If the shared access signature token credential could not be created using the connection string.

    • connectionString

      public EventHubClientBuilder connectionString(String connectionString, String eventHubName)
      Sets the credential information given a connection string to the Event Hubs namespace and name to a specific Event Hub instance.
      Parameters:
      connectionString - The connection string to use for connecting to the Event Hubs namespace; it is expected that the shared access key properties are contained in this connection string, but not the Event Hub name.
      eventHubName - The name of the Event Hub to connect the client to.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      NullPointerException - if connectionString or eventHubName is null.
      IllegalArgumentException - if connectionString or eventHubName is an empty string. Or, if the connectionString contains the Event Hub name.
      com.azure.core.exception.AzureException - If the shared access signature token credential could not be created using the connection string.

    • configuration

      public EventHubClientBuilder configuration(com.azure.core.util.Configuration configuration)
      Sets the configuration store that is used during construction of the service client.

      If not specified, the default configuration store is used to configure the EventHubAsyncClient. Use Configuration.NONE to bypass using configuration settings during construction.

      Specified by:
      configuration in interface com.azure.core.client.traits.ConfigurationTrait<EventHubClientBuilder>
      Parameters:
      configuration - The configuration store used to configure the EventHubAsyncClient.
      Returns:
      The updated EventHubClientBuilder object.

    • customEndpointAddress

      public EventHubClientBuilder customEndpointAddress(String customEndpointAddress)
      Sets a custom endpoint address when connecting to the Event Hubs service. This can be useful when your network does not allow connecting to the standard Azure Event Hubs endpoint address, but does allow connecting through an intermediary. For example: https://my.custom.endpoint.com:55300.

      If no port is specified, the default port for the transport type is used.

      Parameters:
      customEndpointAddress - The custom endpoint address.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if customEndpointAddress cannot be parsed into a valid URL.

    • fullyQualifiedNamespace

      public EventHubClientBuilder fullyQualifiedNamespace(String fullyQualifiedNamespace)
      Sets the fully qualified name for the Event Hubs namespace.
      Parameters:
      fullyQualifiedNamespace - The fully qualified name for the Event Hubs namespace. This is likely to be similar to "{your-namespace}.servicebus.windows.net".
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if fullyQualifiedNamespace is an empty string.
      NullPointerException - if fullyQualifiedNamespace is null.

    • eventHubName

      public EventHubClientBuilder eventHubName(String eventHubName)
      Sets the name of the Event Hub to connect the client to.
      Parameters:
      eventHubName - The name of the Event Hub to connect the client to.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if eventHubName is an empty string.
      NullPointerException - if eventHubName is null.

    • shareConnection

      public EventHubClientBuilder shareConnection()
      Toggles the builder to use the same connection for producers or consumers that are built from this instance. By default, a new connection is constructed and used created for each Event Hub consumer or producer created.
      Returns:
      The updated EventHubClientBuilder object.

    • credential

      public EventHubClientBuilder credential(String fullyQualifiedNamespace, String eventHubName, com.azure.core.credential.TokenCredential credential)
      Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.
      Parameters:
      fullyQualifiedNamespace - The fully qualified name for the Event Hubs namespace. This is likely to be similar to "{your-namespace}.servicebus.windows.net".
      eventHubName - The name of the Event Hub to connect the client to.
      credential - The token credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if fullyQualifiedNamespace or eventHubName is an empty string.
      NullPointerException - if fullyQualifiedNamespace, eventHubName, credentials is null.

    • credential

      public EventHubClientBuilder credential(com.azure.core.credential.TokenCredential credential)
      Sets the TokenCredential used to authorize requests sent to the service. Refer to the Azure SDK for Java identity and authentication documentation for more details on proper usage of the TokenCredential type.
      Specified by:
      credential in interface com.azure.core.client.traits.TokenCredentialTrait<EventHubClientBuilder>
      Parameters:
      credential - The token credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      NullPointerException - if credentials is null.

    • credential

      public EventHubClientBuilder credential(String fullyQualifiedNamespace, String eventHubName, com.azure.core.credential.AzureNamedKeyCredential credential)
      Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.
      Parameters:
      fullyQualifiedNamespace - The fully qualified name for the Event Hubs namespace. This is likely to be similar to "{your-namespace}.servicebus.windows.net".
      eventHubName - The name of the Event Hub to connect the client to.
      credential - The shared access name and key credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if fullyQualifiedNamespace or eventHubName is an empty string.
      NullPointerException - if fullyQualifiedNamespace, eventHubName, credentials is null.

    • credential

      public EventHubClientBuilder credential(com.azure.core.credential.AzureNamedKeyCredential credential)
      Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.
      Specified by:
      credential in interface com.azure.core.client.traits.AzureNamedKeyCredentialTrait<EventHubClientBuilder>
      Parameters:
      credential - The shared access name and key credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      NullPointerException - if credentials is null.

    • credential

      public EventHubClientBuilder credential(String fullyQualifiedNamespace, String eventHubName, com.azure.core.credential.AzureSasCredential credential)
      Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.
      Parameters:
      fullyQualifiedNamespace - The fully qualified name for the Event Hubs namespace. This is likely to be similar to "{your-namespace}.servicebus.windows.net".
      eventHubName - The name of the Event Hub to connect the client to.
      credential - The shared access signature credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if fullyQualifiedNamespace or eventHubName is an empty string.
      NullPointerException - if fullyQualifiedNamespace, eventHubName, credentials is null.

    • credential

      public EventHubClientBuilder credential(com.azure.core.credential.AzureSasCredential credential)
      Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.
      Specified by:
      credential in interface com.azure.core.client.traits.AzureSasCredentialTrait<EventHubClientBuilder>
      Parameters:
      credential - The shared access signature credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      NullPointerException - if credentials is null.

    • proxyOptions

      public EventHubClientBuilder proxyOptions(com.azure.core.amqp.ProxyOptions proxyOptions)
      Sets the proxy configuration to use for EventHubAsyncClient. When a proxy is configured, AmqpTransportType.AMQP_WEB_SOCKETS must be used for the transport type.
      Specified by:
      proxyOptions in interface com.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
      Parameters:
      proxyOptions - The proxy configuration to use.
      Returns:
      The updated EventHubClientBuilder object.

    • transportType

      public EventHubClientBuilder transportType(com.azure.core.amqp.AmqpTransportType transport)
      Sets the transport type by which all the communication with Azure Event Hubs occurs. Default value is AmqpTransportType.AMQP.
      Specified by:
      transportType in interface com.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
      Parameters:
      transport - The transport type to use.
      Returns:
      The updated EventHubClientBuilder object.

    • retry

      @Deprecated public EventHubClientBuilder retry(com.azure.core.amqp.AmqpRetryOptions retryOptions)
      Deprecated.
      Replaced by retryOptions(AmqpRetryOptions).
      Sets the retry policy for EventHubAsyncClient. If not specified, the default retry options are used.
      Parameters:
      retryOptions - The retry policy to use.
      Returns:
      The updated EventHubClientBuilder object.

    • retryOptions

      public EventHubClientBuilder retryOptions(com.azure.core.amqp.AmqpRetryOptions retryOptions)
      Sets the retry policy for EventHubAsyncClient. If not specified, the default retry options are used.
      Specified by:
      retryOptions in interface com.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
      Parameters:
      retryOptions - The retry policy to use.
      Returns:
      The updated EventHubClientBuilder object.

    • consumerGroup

      public EventHubClientBuilder consumerGroup(String consumerGroup)
      Sets the name of the consumer group this consumer is associated with. Events are read in the context of this group. The name of the consumer group that is created by default is "$Default".
      Parameters:
      consumerGroup - The name of the consumer group this consumer is associated with. Events are read in the context of this group. The name of the consumer group that is created by default is "$Default".
      Returns:
      The updated EventHubClientBuilder object.

    • prefetchCount

      public EventHubClientBuilder prefetchCount(int prefetchCount)
      Sets the count used by the receiver to control the number of events per partition the Event Hub consumer will actively receive and queue locally without regard to whether a receive operation is currently active.
      Parameters:
      prefetchCount - The amount of events per partition to queue locally. Defaults to 500 events per partition.
      Returns:
      The updated EventHubClientBuilder object.
      Throws:
      IllegalArgumentException - if prefetchCount is less than 1 or greater than 8000.

    • buildAsyncConsumerClient

      public EventHubConsumerAsyncClient buildAsyncConsumerClient()
      Creates a new EventHubConsumerAsyncClient based on the options set on this builder. Every time buildAsyncConsumer() is invoked, a new instance of EventHubConsumerAsyncClient is created.
      Returns:
      A new EventHubConsumerAsyncClient with the configured options.
      Throws:
      IllegalArgumentException - If shared connection is not used and the credentials have not been set using either connectionString(String) or credential(String, String, TokenCredential). Also, if consumerGroup(String) have not been set. And if a proxy is specified but the transport type is not web sockets. Or, if the eventHubName has not been set.

    • buildConsumerClient

      public EventHubConsumerClient buildConsumerClient()
      Creates a new EventHubConsumerClient based on the options set on this builder. Every time buildConsumer() is invoked, a new instance of EventHubConsumerClient is created.
      Returns:
      A new EventHubConsumerClient with the configured options.
      Throws:
      IllegalArgumentException - If shared connection is not used and the credentials have not been set using either connectionString(String) or credential(String, String, TokenCredential). Also, if consumerGroup(String) have not been set. And if a proxy is specified but the transport type is not web sockets. Or, if the eventHubName has not been set.

    • buildAsyncProducerClient

      public EventHubProducerAsyncClient buildAsyncProducerClient()
      Creates a new EventHubProducerAsyncClient based on options set on this builder. Every time buildAsyncProducer() is invoked, a new instance of EventHubProducerAsyncClient is created.
      Returns:
      A new EventHubProducerAsyncClient instance with all the configured options.
      Throws:
      IllegalArgumentException - If shared connection is not used and the credentials have not been set using either connectionString(String) or credential(String, String, TokenCredential). Or, if a proxy is specified but the transport type is not web sockets. Or, if the eventHubName has not been set.

    • buildProducerClient

      public EventHubProducerClient buildProducerClient()
      Creates a new EventHubProducerClient based on options set on this builder. Every time buildAsyncProducer() is invoked, a new instance of EventHubProducerClient is created.
      Returns:
      A new EventHubProducerClient instance with all the configured options.
      Throws:
      IllegalArgumentException - If shared connection is not used and the credentials have not been set using either connectionString(String) or credential(String, String, TokenCredential). Or, if a proxy is specified but the transport type is not web sockets. Or, if the eventHubName has not been set.