com.microsoft.azure.eventhubs

Classes

AuthorizationFailedException

Authorization failed exception is thrown when error is encountered during authorizing user's permission to run the intended operations. When encountered this exception user should check whether the token/key provided in the connection string (e.g. one passed to EventHubClient#create(String, ScheduledExecutorService)) is valid, and has correct execution right for the intended operations (e.g. Receive call will need Listen claim associated with the key/token).

BatchOptions

BatchOptions is used to create EventDataBatches.

If you're creating EventDataBatches with EventHubClient, then you can set a partitionKey and maxMessageSize using the .with() method. Alternatively, if you'd like the default settings, simply construct BatchOptions with the void constructor. Default settings:

  • partitionKey is null

  • maxMessageSize is the maximum allowed size

If you're creating EventDataBatches with PartitionSender, then you can only set a maxMessageSize using the .with() method. Alternatively, if you'd like the default settings, simply construct BatchOptions with the void constructor. Default settings:

  • maxMessageSize is the maximum allowed size

  • Note: if you set a partition key, an IllegalArgumentException will be thrown.

To construct either type of batch, create a BatchOptions object and pass it into the appropriate createBatch method. If using PartitionSender, then use (PartitionSender#createBatch(BatchOptions). If using EventHubClient, then use EventHubClient#createBatch(BatchOptions).

// Note: For all examples, 'client' is an instance of EventHubClient. The usage is the same for PartitionSender,
    however, you can NOT set a partition key when using PartitionSender
    
    // Create EventDataBatch with defaults
    EventDataBatch edb1 = client.createBatch();
    
    // Create EventDataBatch with custom partitionKey
    BatchOptions options = new BatchOptions().with( options -> options.partitionKey = "foo");
    EventDataBatch edb2 = client.createBatch(options);
    
    // Create EventDataBatch with custom partitionKey and maxMessageSize
    BatchOptions options = new BatchOptions().with ( options -> {
        options.partitionKey = "foo";
        options.maxMessageSize = 100 * 1024;
    };
    EventDataBatch edb3 = client.createBatch(options);
    

CommunicationException

This exception is thrown when there is a client side connectivity issue. When receiving this exception user should check client connectivity settings to the service:

  • Check for correct hostname and port number used in endpoint.

  • Check for any possible proxy settings that can block amqp ports

  • Check for any firewall settings that can block amqp ports

  • Check for any general network connectivity issues, as well as network latency.

ConnectionStringBuilder

ConnectionStringBuilder can be used to construct a connection string which can establish communication with Event Hub instances. In addition to constructing a connection string, the ConnectionStringBuilder can be used to modify an existing connection string.

Sample Code:

// Construct a new connection string
       ConnectionStringBuilder connectionStringBuilder = new ConnectionStringBuilder()
           .setNamespaceName("EventHubsNamespaceName")
           .setEventHubName("EventHubsEntityName")
           .setSasKeyName("SharedAccessSignatureKeyName")
           .setSasKey("SharedAccessSignatureKey")
    
    string connString = connectionStringBuilder.build();
    
    // Modify an existing connection string
    ConnectionStringBuilder connectionStringBuilder = new ConnectionStringBuilder(existingConnectionString)
        .setEventHubName("SomeOtherEventHubsName")
        .setOperationTimeout(Duration.ofSeconds(30)
    
    string connString = connectionStringBuilder.build();
    

A connection string is basically a string consisting of key-value pairs separated by ";". The basic format is {{ <}key{>}={ <}value{>}[;{ <}key{>}={ <}value{>}]} where supported key name are as follow:

  • Endpoint - the URL that contains the EventHubs namespace

  • EntityPath - the EventHub name which you are connecting to

  • SharedAccessKeyName - the key name to the corresponding shared access policy rule for the namespace, or entity.

  • SharedAccessKey - the key for the corresponding shared access policy rule of the namespace or entity.

ErrorContext
EventData.SystemProperties
EventHubException

This is the base exception that service bus will produce for all error cases.

EventHubRuntimeInformation

Holds information about Event Hubs which can come handy while performing data-plane operations like EventHubClient#createPartitionSender(String) and EventHubClient#createReceiver(String, String, EventPosition)

IllegalConnectionStringFormatException

This exception is thrown when the connection string provided does not meet the requirement for connection.

IllegalEntityException

This exception is thrown for the following reasons:

  • When the entity user attempted to connect does not exist

  • The entity user wants to connect is disabled

OperationCancelledException

This exception is thrown when the underlying AMQP layer encounter an abnormal link abort or disconnect of connection in an unexpected fashion.

PartitionRuntimeInformation
PayloadSizeExceededException

this exception is thrown when user attempts to send a event data or brokered message that has exceeded the allowed payload size as defined by the service. Note that in a batch send scenario the limit can include possible batch overhead.

QuotaExceededException
ReceiverDisconnectedException

This exception is thrown when a EventHubReceiver is being disconnected because of one of the following reason:

  • user attempts to connect a non-epoch receiver to a event hub partition, when there is an epoch receiver connected to the partition.

  • you are using an epoch receiver for a given partition but another epoch receiver with a higher epoch value connects to the same partition.

User should make sure either all code are using non-epoch receivers, or ensure that there is only one epoch receiver processing a given partition at any given point in time.

ReceiverOptions

Represents various optional behaviors which can be turned on or off during the creation of a PartitionReceiver.

ReceiverRuntimeInformation

Represents the temporal end of stream information of an EventHubs Partition.

RetryPolicy
ServerBusyException

Server busy exception is thrown when the current entity's activity has put excessive load onto the service. When encountered this exception user should wait at least 4 seconds before any retry/runtime operations for the said entity again.

TimeoutException

This exception is thrown when the operation has exceeded the predetermined time limit. User should check connectivity is healthy between client process and service.

Interfaces

EventData

The data structure encapsulating the Event being sent-to and received-from EventHubs. Each EventHubs partition can be visualized as a Stream of EventData.

Serializing a received EventData with AMQP sections other than ApplicationProperties (with primitive java types) and Data section is not supported.

Here's how AMQP message sections map to EventData. Here's the reference used for AMQP 1.0 specification: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-complete-v1.0-os.pdf

i.   getProperties() - AMQPMessage.ApplicationProperties section
ii.  getBytes() - if AMQPMessage.Body has Data section
iii. getObject() - if AMQPMessage.Body has AMQPValue or AMQPSequence sections
While using client libraries released by Microsoft Azure EventHubs, sections (i) and (ii) alone are sufficient. Section (iii) is used for advanced scenarios, where the sending application uses third-party AMQP library to send the message to EventHubs and the receiving application uses this client library to receive EventData.

EventDataBatch

Helper for creating a batch/collection of EventData objects to be used while Sending to EventHubs

EventHubClient

Anchor class - all EventHub client operations STARTS here.

EventPosition

Defines a position of an EventData in the event hub partition. The position can be an Offset, Sequence Number, or EnqueuedTime.

PartitionReceiveHandler

The handler to invoke after receiving EventDatas from Microsoft Azure EventHubs. Use any implementation of this abstract class to specify user action when using PartitionReceiver's setReceiveHandler().

PartitionReceiver

This is a logical representation of receiving from a EventHub partition.

A PartitionReceiver is tied to a ConsumerGroup + EventHub Partition combination.

  • If an epoch based PartitionReceiver (i.e., PartitionReceiver.getEpoch != 0) is created, EventHubs service will guarantee only 1 active receiver exists per ConsumerGroup + Partition combo. This is the recommended approach to create a PartitionReceiver.

  • Multiple receivers per ConsumerGroup + Partition combo can be created using non-epoch receivers.

PartitionSender

This sender class is a logical representation of sending events to a specific EventHub partition. Do not use this class if you do not care about sending events to specific partitions. Instead, use EventHubClient#send method.

Enums

TransportType

All TransportType switches available for communicating to EventHubs service.