First published on on Mar 01, 2018
Azure Event Hubs Java ecosystem reaches a new milestone with our newest and major release for Event Hubs Java library! We are happy and excited to announce the
general availability of our new EventHubs and EventProcessorHost in version 1.0.0, clients for JAVA
.
These libraries allow customers to enjoy a solid Java experience with Azure Event Hubs as it comes complete with native functionality. Enjoy these native clients to ingest into Event Hubs or receive events using Event Processor Host.
New to Event Hubs and want to learn how to send and receive events? These articles explain all the details, Stream events to Azure Event Hubs/Process events from Event Hubs.
We have samples you can try, using these libraries for streaming and processing
.
Want to update your clients with this new version? The maven packages can be found
here
. Alternatively, you can download from
here.
Our GitHub release for new clients can be found
here
.
This library can be referenced in Maven projects using the following dependency declaration
<
dependency
>
<
groupId
>com.microsoft.azure</
groupId
>
<
artifactId
>azure-eventhubs</
artifactId
>
<
version
>1.0.0</
version
>
</
dependency
>
<
dependency
>
<
groupId
>com.microsoft.azure</
groupId
>
<
artifactId
>azure-eventhubs-eph</
artifactId
>
<
version
>1.0.0</
version
>
</
dependency
>
Below is the release summary (which can also be found on GitHub –
https://github.com/Azure/azure-event-hubs-java/releases/tag/1.0.0
)
1.0.0
This major release targets the following additions
com.microsoft.azure.eventhubs
Support user threadPool : All asynchronous tasks are handed off to the ‘Executor’ that is provided while creating the ‘EventHubClient’. This means EventHubs library no longer creates any threads or a threadPool.
Support for ‘PartitionReceiver’: ‘PartitionReceiver’ is now based out of ‘EventData.SequenceNumber’, you can now use ‘EventPosition.fromSequenceNumber(sequenceNumber)’ to create the ‘PartitionReceiver’ from a sequence number
ConnectionStringBuilder
supports setters for all properties in fluent-style. Supports adding properties to an existing
ConnectionString
PartitionReceiveHandler
is changed from
abstract class
to
interface
.
PartitionReceiver.END_OF_STREAM
and
PartitionReceiver.START_OF_STREAM
are replaced by
EventPosition.fromEndOfStream()
and
EventPosition.fromStartOfStream()
respectively.
com.microsoft.azure.eventprocessorhost
Previously there was a central loop which periodically scanned the state of all leases and was responsible for taking unowned leases and renewing leases owned by the host instance. The two parts (taking and renewing) have been separated and both are now parallel rather than iterative. This greatly reduces the impact of Azure Storage latency when using the default lease manager.
All code has been refactored to use
CompletableFuture
and composition. There are no long-running threads and all sleeps have been replaced with scheduled execution.
Breaking API changes
Changes for com.microsoft.azure.eventhubs
EventData constructors are replaced with EventData.create(…) variants
Factory method to create an instance of EventHubClient from connection string is renamed from fromConnectionString to create.
Factory method to create an instance of EventHubClient requires additional parameter – Executor.
Factory methods to create PartitionReceiver instances require a new parameter EventPosition – as an abstraction to the position of the EventData (as opposed to taking offset, dateTime or sequenceNumber).
Changes for com.microsoft.azure.eventprocessorhost
All deprecated constructors and methods have been removed
EventProcessorHost no longer offers constructors, which automatically generate a hostname. This means that all constructors will requires the user to supply a hostname. To generate a unique hostname, we recommend using the static EventProcessorHost.createHostName utility method, which appends the UUID to a user-supplied string.
If you are using Azure Storage for your lease management and checkpointing, the EventProcessorHost constructor requires a user supplied Storage container name. This container name should be the same for all EventProcessorHost instances operating on the name event hub and consumer group. This shared store is what allows the instances to divide ownership of the event hub partitions amongst them.
For EventProcessorHost constructors which take a user-supplied threadpool, the type is now changed from ExecutorService to ScheduledExecutorService
The EventProcessorHost.setAutoExecutorShutdown and forceExectorShutdown methods are removed. An internal threadpool will always be shut down when the EventProcessorHost instance is shut down via unregisterEventProcessor, and a user-supplied threadpool will never be shut down.
The Client for Java now uses class EventPosition to represent a position in the stream of events. The initial offset provider previously in EventProcessorOptions has been renamed to initial position provider and supports EventPosition.
The EventProcessorHost.register* methods now return a CompletableFuture which completes when initialization is finished. These methods no longer throw directly. All errors during initialization are signaled by completing the CompletableFuture with an exception
unregisterEventProcessor is now async and returns a CompletableFuture which completes when the EventProcessorHost instance has finished shutting down. Failures during shutdown are signaled by completing the CompletableFuture with an exception
The PartitionContext.checkpoint methods are now async and return a CompletableFuture. The checkpoint is not guaranteed to be persisted until the CompletableFuture completes. Failures during checkpointing are signaled by completing the CompletableFuture with an exception
The ICheckpointManager and ILeaseManager interfaces have been changed to use CompletableFuture instead of Future. This change only affects those implementing checkpoint and lease managers.
As part of the parallelization effort, the internals were refactored to use CompletableFutures and composition. There are no long-running threads and all sleeps have been replaced by scheduling. If the user is supplying a threadpool, there is no minimum number of available threads required to avoid starvation or deadlock: Event Processor Host can make progress, although slowly, as long as even one thread is available. More threads are recommended, of course, and achieving high performance requires multiple threads
What is next?
Check out this column for updated GitHub samples for Event Hubs using the new Java clients!
Try this new library and let us know what you think!
Happy event-ing!
Event Hubs team