Class 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>
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:
connectionString(String)
with a connection string to a specific Event Hub.connectionString(String, String)
with an Event Hub namespace connection string and the Event Hub name.credential(String, String, TokenCredential)
with the fully qualified namespace, Event Hub name, and a set of credentials authorized to use the Event Hub.credential(String, String, AzureSasCredential)
with the fully qualified namespace, Event Hub name, and a shared access signature for the Event Hub.credential(String, String, AzureNamedKeyCredential)
with the fully qualified namespace, Event Hub name, and a named key credential. The named key can be found in the Azure Portal by navigating to the Event Hub resource, selecting "Shared access policies" under the Settings section.credential(TokenCredential)
,credential(AzureSasCredential)
, andcredential(AzureNamedKeyCredential)
overloads can be used with its respective credentials.fullyQualifiedNamespace(String)
andeventHubName(String)
must be set as well.
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();
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The name of the default consumer group in the Event Hubs service. -
Constructor Summary
ConstructorDescriptionCreates a new instance with the default transportAmqpTransportType.AMQP
and a non-shared connection. -
Method Summary
Modifier and TypeMethodDescriptionCreates a newEventHubConsumerAsyncClient
based on the options set on this builder.Creates a newEventHubProducerAsyncClient
based on options set on this builder.Creates a newEventHubConsumerClient
based on the options set on this builder.Creates a newEventHubProducerClient
based on options set on this builder.clientOptions
(com.azure.core.util.ClientOptions clientOptions) Sets the client options.configuration
(com.azure.core.util.Configuration configuration) Sets the configuration store that is used during construction of the service client.connectionString
(String connectionString) Sets the credential information given a connection string to the Event Hub instance or the Event Hubs namespace.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.consumerGroup
(String consumerGroup) Sets the name of the consumer group this consumer is associated with.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.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.credential
(com.azure.core.credential.TokenCredential credential) Sets theTokenCredential
used to authorize requests sent to the service.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.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.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.customEndpointAddress
(String customEndpointAddress) Sets a custom endpoint address when connecting to the Event Hubs service.eventHubName
(String eventHubName) Sets the name of the Event Hub to connect the client to.fullyQualifiedNamespace
(String fullyQualifiedNamespace) Sets the fully qualified name for the Event Hubs namespace.prefetchCount
(int prefetchCount) Sets the count used by the receiver to control the number of events the Event Hub consumer will actively receive and queue locally without regard to whether a receive operation is currently active.proxyOptions
(com.azure.core.amqp.ProxyOptions proxyOptions) Sets the proxy configuration to use forEventHubAsyncClient
.retry
(com.azure.core.amqp.AmqpRetryOptions retryOptions) Deprecated.retryOptions
(com.azure.core.amqp.AmqpRetryOptions retryOptions) Sets the retry policy forEventHubAsyncClient
.Toggles the builder to use the same connection for producers or consumers that are built from this instance.transportType
(com.azure.core.amqp.AmqpTransportType transport) Sets the transport type by which all the communication with Azure Event Hubs occurs.
-
Field Details
-
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 transportAmqpTransportType.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
-
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 interfacecom.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
- ifconnectionString
is null or empty. IffullyQualifiedNamespace
in the connection string is null.NullPointerException
- if a credential could not be extractedcom.azure.core.exception.AzureException
- If the shared access signature token credential could not be created using the connection string.
-
clientOptions
Sets the client options.- Specified by:
clientOptions
in interfacecom.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
- Parameters:
clientOptions
- The client options.- Returns:
- The updated
EventHubClientBuilder
object.
-
connectionString
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
- ifconnectionString
oreventHubName
is null.IllegalArgumentException
- ifconnectionString
oreventHubName
is an empty string. Or, if theconnectionString
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
Sets the configuration store that is used during construction of the service client. If not specified, the default configuration store is used to configure theEventHubAsyncClient
. UseConfiguration.NONE
to bypass using configuration settings during construction.- Specified by:
configuration
in interfacecom.azure.core.client.traits.ConfigurationTrait<EventHubClientBuilder>
- Parameters:
configuration
- The configuration store used to configure theEventHubAsyncClient
.- Returns:
- The updated
EventHubClientBuilder
object.
-
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
- ifcustomEndpointAddress
cannot be parsed into a validURL
.
-
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
- iffullyQualifiedNamespace
is an empty string.NullPointerException
- iffullyQualifiedNamespace
is null.
-
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
- ifeventHubName
is an empty string.NullPointerException
- ifeventHubName
is null.
-
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
- iffullyQualifiedNamespace
oreventHubName
is an empty string.NullPointerException
- iffullyQualifiedNamespace
,eventHubName
,credentials
is null.
-
credential
Sets theTokenCredential
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 theTokenCredential
type.- Specified by:
credential
in interfacecom.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
- ifcredentials
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
- iffullyQualifiedNamespace
oreventHubName
is an empty string.NullPointerException
- iffullyQualifiedNamespace
,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 interfacecom.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
- ifcredentials
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
- iffullyQualifiedNamespace
oreventHubName
is an empty string.NullPointerException
- iffullyQualifiedNamespace
,eventHubName
,credentials
is null.
-
credential
Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.- Specified by:
credential
in interfacecom.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
- ifcredentials
is null.
-
proxyOptions
Sets the proxy configuration to use forEventHubAsyncClient
. When a proxy is configured,AmqpTransportType.AMQP_WEB_SOCKETS
must be used for the transport type.- Specified by:
proxyOptions
in interfacecom.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
- Parameters:
proxyOptions
- The proxy configuration to use.- Returns:
- The updated
EventHubClientBuilder
object.
-
transportType
Sets the transport type by which all the communication with Azure Event Hubs occurs. Default value isAmqpTransportType.AMQP
.- Specified by:
transportType
in interfacecom.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
- Parameters:
transport
- The transport type to use.- Returns:
- The updated
EventHubClientBuilder
object.
-
retry
Deprecated.Replaced byretryOptions(AmqpRetryOptions)
.Sets the retry policy forEventHubAsyncClient
. If not specified, the default retry options are used.- Parameters:
retryOptions
- The retry policy to use.- Returns:
- The updated
EventHubClientBuilder
object.
-
retryOptions
Sets the retry policy forEventHubAsyncClient
. If not specified, the default retry options are used.- Specified by:
retryOptions
in interfacecom.azure.core.amqp.client.traits.AmqpTrait<EventHubClientBuilder>
- Parameters:
retryOptions
- The retry policy to use.- Returns:
- The updated
EventHubClientBuilder
object.
-
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
Sets the count used by the receiver to control the number of events 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 to queue locally.- Returns:
- The updated
EventHubClientBuilder
object. - Throws:
IllegalArgumentException
- ifprefetchCount
is less than1
or greater than8000
.
-
buildAsyncConsumerClient
Creates a newEventHubConsumerAsyncClient
based on the options set on this builder. Every timebuildAsyncConsumer()
is invoked, a new instance ofEventHubConsumerAsyncClient
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 eitherconnectionString(String)
orcredential(String, String, TokenCredential)
. Also, ifconsumerGroup(String)
have not been set. And if a proxy is specified but the transport type is notweb sockets
. Or, if theeventHubName
has not been set.
-
buildConsumerClient
Creates a newEventHubConsumerClient
based on the options set on this builder. Every timebuildConsumer()
is invoked, a new instance ofEventHubConsumerClient
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 eitherconnectionString(String)
orcredential(String, String, TokenCredential)
. Also, ifconsumerGroup(String)
have not been set. And if a proxy is specified but the transport type is notweb sockets
. Or, if theeventHubName
has not been set.
-
buildAsyncProducerClient
Creates a newEventHubProducerAsyncClient
based on options set on this builder. Every timebuildAsyncProducer()
is invoked, a new instance ofEventHubProducerAsyncClient
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 eitherconnectionString(String)
orcredential(String, String, TokenCredential)
. Or, if a proxy is specified but the transport type is notweb sockets
. Or, if theeventHubName
has not been set.
-
buildProducerClient
Creates a newEventHubProducerClient
based on options set on this builder. Every timebuildAsyncProducer()
is invoked, a new instance ofEventHubProducerClient
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 eitherconnectionString(String)
orcredential(String, String, TokenCredential)
. Or, if a proxy is specified but the transport type is notweb sockets
. Or, if theeventHubName
has not been set.
-
retryOptions(AmqpRetryOptions)
.