public class EventHubClientBuilder extends Object
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.
In addition, consumer group is required when creating EventHubConsumerAsyncClient
or
EventHubConsumerClient
.
Creating an asynchronous EventHubProducerAsyncClient
using Event Hubs namespace connection string
In the sample, the namespace connection string is used to create an asynchronous Event Hub producer. Notice that
"EntityPath"
is not a component in the connection string.
// The required parameter is a way to authenticate with Event Hubs using credentials. // The connectionString provides a way to authenticate with Event Hub.EventHubProducerAsyncClient
producer = newEventHubClientBuilder
() .connectionString( "Endpoint={fully-qualified-namespace};SharedAccessKeyName={policy-name};SharedAccessKey={key}", "event-hub-name") .buildAsyncProducerClient();
Creating a synchronous EventHubConsumerClient
using an Event Hub instance connection string
In the sample, the namespace connection string is used to create a synchronous Event Hub consumer. Notice that
"EntityPath"
is in the connection string.
// The required parameters are `consumerGroup`, and a way to authenticate with Event Hubs using credentials.EventHubConsumerClient
consumer = newEventHubClientBuilder
() .connectionString( "Endpoint={eh-namespace};SharedAccessKeyName={policy-name};SharedAccessKey={key};Entity-Path={hub-name}") .consumerGroup("$DEFAULT") .buildConsumerClient();
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()
.
// Toggling `shareConnection` instructs the builder to use the same underlying connection // for each consumer or producer created using the same builder instance.EventHubClientBuilder
builder = newEventHubClientBuilder
() .connectionString("event-hubs-instance-connection-string") .shareConnection(); // Both the producer and consumer created share the same underlying connection.EventHubProducerAsyncClient
producer = builder.buildAsyncProducerClient();EventHubConsumerAsyncClient
consumer = builder .consumerGroup("my-consumer-group") .buildAsyncConsumerClient();
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_CONSUMER_GROUP_NAME
The name of the default consumer group in the Event Hubs service.
|
Constructor and Description |
---|
EventHubClientBuilder()
Creates a new instance with the default transport
AmqpTransportType.AMQP and a non-shared connection. |
Modifier and Type | Method and Description |
---|---|
EventHubConsumerAsyncClient |
buildAsyncConsumerClient()
Creates a new
EventHubConsumerAsyncClient based on the options set on this builder. |
EventHubProducerAsyncClient |
buildAsyncProducerClient()
Creates a new
EventHubProducerAsyncClient based on options set on this builder. |
EventHubConsumerClient |
buildConsumerClient()
Creates a new
EventHubConsumerClient based on the options set on this builder. |
EventHubProducerClient |
buildProducerClient()
Creates a new
EventHubProducerClient based on options set on this builder. |
EventHubClientBuilder |
configuration(Configuration configuration)
Sets the configuration store that is used during construction of the service client.
|
EventHubClientBuilder |
connectionString(String connectionString)
Sets the credential information given a connection string to the Event Hub instance.
|
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.
|
EventHubClientBuilder |
consumerGroup(String consumerGroup)
Sets the name of the consumer group this consumer is associated with.
|
EventHubClientBuilder |
credential(String fullyQualifiedNamespace,
String eventHubName,
TokenCredential credential)
Sets the credential information for which Event Hub instance to connect to, and how to authorize against it.
|
EventHubClientBuilder |
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.
|
EventHubClientBuilder |
proxyOptions(ProxyOptions proxyOptions)
Sets the proxy configuration to use for
EventHubAsyncClient . |
EventHubClientBuilder |
retry(AmqpRetryOptions retryOptions)
Sets the retry policy for
EventHubAsyncClient . |
EventHubClientBuilder |
shareConnection()
Toggles the builder to use the same connection for producers or consumers that are built from this instance.
|
EventHubClientBuilder |
transportType(AmqpTransportType transport)
Sets the transport type by which all the communication with Azure Event Hubs occurs.
|
public static final String DEFAULT_CONSUMER_GROUP_NAME
public EventHubClientBuilder()
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.public EventHubClientBuilder connectionString(String connectionString)
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.
connectionString
- The connection string to use for connecting to the Event Hub instance. It is expected
that the Event Hub name and the shared access key properties are contained in this connection string.EventHubClientBuilder
object.IllegalArgumentException
- if connectionString
is null or empty. Or, the connectionString
does not contain the "EntityPath" key, which is the name of the Event Hub instance.AzureException
- If the shared access signature token credential could not be created using the
connection string.public EventHubClientBuilder connectionString(String connectionString, String eventHubName)
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.EventHubClientBuilder
object.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.AzureException
- If the shared access signature token credential could not be created using the connection
string.public EventHubClientBuilder configuration(Configuration configuration)
EventHubAsyncClient
. Use
Configuration.NONE
to bypass using configuration settings during construction.configuration
- The configuration store used to configure the EventHubAsyncClient
.EventHubClientBuilder
object.public EventHubClientBuilder shareConnection()
EventHubClientBuilder
object.public EventHubClientBuilder credential(String fullyQualifiedNamespace, String eventHubName, TokenCredential credential)
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.EventHubClientBuilder
object.IllegalArgumentException
- if fullyQualifiedNamespace
or eventHubName
is an empty string.NullPointerException
- if fullyQualifiedNamespace
, eventHubName
, credentials
is
null.public EventHubClientBuilder proxyOptions(ProxyOptions proxyOptions)
EventHubAsyncClient
. When a proxy is configured, AmqpTransportType.AMQP_WEB_SOCKETS
must be used for the transport type.proxyOptions
- The proxy configuration to use.EventHubClientBuilder
object.public EventHubClientBuilder transportType(AmqpTransportType transport)
AmqpTransportType.AMQP
.transport
- The transport type to use.EventHubClientBuilder
object.public EventHubClientBuilder retry(AmqpRetryOptions retryOptions)
EventHubAsyncClient
. If not specified, the default retry options are used.retryOptions
- The retry policy to use.EventHubClientBuilder
object.public EventHubClientBuilder consumerGroup(String consumerGroup)
"$Default"
.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"
.EventHubClientBuilder
object.public EventHubClientBuilder prefetchCount(int prefetchCount)
prefetchCount
- The amount of events to queue locally.EventHubClientBuilder
object.IllegalArgumentException
- if prefetchCount
is less than 1
or
greater than 8000
.public EventHubConsumerAsyncClient buildAsyncConsumerClient()
EventHubConsumerAsyncClient
based on the options set on this builder. Every time
buildAsyncConsumer()
is invoked, a new instance of EventHubConsumerAsyncClient
is created.EventHubConsumerAsyncClient
with the configured options.IllegalArgumentException
- If shared connection is not used and the credentials have not been set using
either EventHubClientBuilder.connectionString(String)
or EventHubClientBuilder.credential(String, String, TokenCredential)
. Also, if
EventHubClientBuilder.consumerGroup(String)
have not been set. And if a proxy is specified but the transport type is not
web sockets
.public EventHubConsumerClient buildConsumerClient()
EventHubConsumerClient
based on the options set on this builder. Every time
buildConsumer()
is invoked, a new instance of EventHubConsumerClient
is created.EventHubConsumerClient
with the configured options.IllegalArgumentException
- If shared connection is not used and the credentials have not been set using
either EventHubClientBuilder.connectionString(String)
or EventHubClientBuilder.credential(String, String, TokenCredential)
. Also, if
EventHubClientBuilder.consumerGroup(String)
have not been set. And if a proxy is specified but the transport type is not
web sockets
.public EventHubProducerAsyncClient buildAsyncProducerClient()
EventHubProducerAsyncClient
based on options set on this builder. Every time
buildAsyncProducer()
is invoked, a new instance of EventHubProducerAsyncClient
is created.EventHubProducerAsyncClient
instance with all the configured options.IllegalArgumentException
- If shared connection is not used and the credentials have not been set using
either EventHubClientBuilder.connectionString(String)
or EventHubClientBuilder.credential(String, String, TokenCredential)
. Or, if a proxy
is specified but the transport type is not web sockets
.public EventHubProducerClient buildProducerClient()
EventHubProducerClient
based on options set on this builder. Every time
buildAsyncProducer()
is invoked, a new instance of EventHubProducerClient
is created.EventHubProducerClient
instance with all the configured options.IllegalArgumentException
- If shared connection is not used and the credentials have not been set using
either EventHubClientBuilder.connectionString(String)
or EventHubClientBuilder.credential(String, String, TokenCredential)
. Or, if a proxy
is specified but the transport type is not web sockets
.Copyright © 2019 Microsoft Corporation. All rights reserved.