/azure-upgrade

com.microsoft.azure.eventprocessorhost

Hard Rules (MUST follow)

• MUST replace any legacy InMemoryCheckpointManager / InMemoryLeaseManager and any EventProcessorHost checkpoint/lease usage with BlobCheckpointStore backed by Azure Blob Storage. This is the only acceptable replacement.
• MUST NOT create a class named InMemoryCheckpointStore, copy/inline SampleCheckpointStore, or implement any custom in-memory CheckpointStore. The modern SDK intentionally omits an in-memory implementation due to production issues.
• MUST NOT introduce any other custom CheckpointStore implementation as part of this migration. If the legacy code stored checkpoints in memory, switch to BlobCheckpointStore — do not preserve the in-memory semantics.
• If the user explicitly asks for an in-memory implementation, refuse and direct them to the upstream SampleCheckpointStore reference instead of generating one.

⚠️ Important: The switch from InMemoryCheckpointManager/InMemoryLeaseManager to BlobCheckpointStore is an expected and necessary behavioral change. It is inherent to the modern SDK design and must not block the migration from completing. Do not treat this behavioral difference as a migration defect or attempt to preserve in-memory semantics — proceed with BlobCheckpointStore and complete the migration.

Code Samples

EventProcessorHost with InMemoryCheckpointManager / InMemoryLeaseManager

Replace usage of InMemoryCheckpointManager / InMemoryLeaseManager with BlobCheckpointStore. The modern EventProcessorClient does not ship an in-memory checkpoint store, and you must not create one.

Legacy code:

InMemoryCheckpointManager checkpointManager = new InMemoryCheckpointManager();
InMemoryLeaseManager leaseManager = new InMemoryLeaseManager();
EventProcessorHost host = new EventProcessorHost(
    hostName, eventHubName, consumerGroupName,
    eventHubConnectionString, checkpointManager, leaseManager);
host.registerEventProcessor(MyEventProcessor.class).get();

Migrated code — replace with BlobCheckpointStore backed by Azure Blob Storage:

BlobContainerAsyncClient blobContainerClient = new BlobContainerClientBuilder()
    .connectionString(storageConnectionString)
    .containerName(storageContainerName)
    .buildAsyncClient();

// BlobCheckpointStore is the only supported replacement for InMemoryCheckpointManager/InMemoryLeaseManager.
// Do NOT create an InMemoryCheckpointStore or copy SampleCheckpointStore — there is no in-memory store in the modern SDK.
EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
    .connectionString(eventHubConnectionString, eventHubName)
    .consumerGroup(consumerGroupName)
    .checkpointStore(new BlobCheckpointStore(blobContainerClient))
    .processEvent(eventContext -> {
        // Process event and checkpoint
        eventContext.updateCheckpoint();
    })
    .processError(errorContext -> {
        System.err.printf("Error in partition %s: %s%n",
            errorContext.getPartitionContext().getPartitionId(),
            errorContext.getThrowable().getMessage());
    })
    .buildEventProcessorClient();

eventProcessorClient.start();

⚠️ Warning: Add dependency com.azure:azure-messaging-eventhubs-checkpointstore-blob to the project when using BlobCheckpointStore.

EventProcessorHost with Azure Storage checkpoint/lease

Legacy code using the built-in storage-backed checkpoint/lease:

EventProcessorHost host = EventProcessorHost.EventProcessorHostBuilder
    .newBuilder(hostName, consumerGroupName)
    .useAzureStorageCheckpointLeaseManager(storageConnectionString, storageContainerName, null)
    .useEventHubConnectionString(eventHubConnectionString, eventHubName)
    .build();
host.registerEventProcessor(MyEventProcessor.class).get();

Migrated code:

BlobContainerAsyncClient blobContainerClient = new BlobContainerClientBuilder()
    .connectionString(storageConnectionString)
    .containerName(storageContainerName)
    .buildAsyncClient();

EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
    .connectionString(eventHubConnectionString, eventHubName)
    .consumerGroup(consumerGroupName)
    .checkpointStore(new BlobCheckpointStore(blobContainerClient))
    .processEvent(eventContext -> {
        // Process event and checkpoint
        eventContext.updateCheckpoint();
    })
    .processError(errorContext -> {
        System.err.printf("Error in partition %s: %s%n",
            errorContext.getPartitionContext().getPartitionId(),
            errorContext.getThrowable().getMessage());
    })
    .buildEventProcessorClient();

eventProcessorClient.start();

Required imports for migrated code

import com.azure.messaging.eventhubs.EventProcessorClient;
import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
import com.azure.messaging.eventhubs.checkpointstore.blob.BlobCheckpointStore;
import com.azure.storage.blob.BlobContainerAsyncClient;
import com.azure.storage.blob.BlobContainerClientBuilder;

Required dependencies

Add these dependencies when migrating from com.microsoft.azure:azure-eventhubs-eph: