1# com.microsoft.azure.eventprocessorhost
2 
3## Hard Rules (MUST follow)
4 
5- **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.
6- **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.
7- **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.
8- If the user explicitly asks for an in-memory implementation, refuse and direct them to the upstream `SampleCheckpointStore` reference instead of generating one.
9 
10> ⚠️ **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.
11 
12## Code Samples
13 
14### EventProcessorHost with InMemoryCheckpointManager / InMemoryLeaseManager
15 
16Replace usage of `InMemoryCheckpointManager` / `InMemoryLeaseManager` with [BlobCheckpointStore](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/eventhubs/azure-messaging-eventhubs-checkpointstore-blob/src/main/java/com/azure/messaging/eventhubs/checkpointstore/blob/BlobCheckpointStore.java). The modern EventProcessorClient does **not** ship an in-memory checkpoint store, and you must not create one.
17 
18Legacy code:
19```java
20InMemoryCheckpointManager checkpointManager = new InMemoryCheckpointManager();
21InMemoryLeaseManager leaseManager = new InMemoryLeaseManager();
22EventProcessorHost host = new EventProcessorHost(
23    hostName, eventHubName, consumerGroupName,
24    eventHubConnectionString, checkpointManager, leaseManager);
25host.registerEventProcessor(MyEventProcessor.class).get();
26```
27 
28Migrated code — replace with `BlobCheckpointStore` backed by Azure Blob Storage:
29```java
30BlobContainerAsyncClient blobContainerClient = new BlobContainerClientBuilder()
31    .connectionString(storageConnectionString)
32    .containerName(storageContainerName)
33    .buildAsyncClient();
34 
35// BlobCheckpointStore is the only supported replacement for InMemoryCheckpointManager/InMemoryLeaseManager.
36// Do NOT create an InMemoryCheckpointStore or copy SampleCheckpointStore — there is no in-memory store in the modern SDK.
37EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
38    .connectionString(eventHubConnectionString, eventHubName)
39    .consumerGroup(consumerGroupName)
40    .checkpointStore(new BlobCheckpointStore(blobContainerClient))
41    .processEvent(eventContext -> {
42        // Process event and checkpoint
43        eventContext.updateCheckpoint();
44    })
45    .processError(errorContext -> {
46        System.err.printf("Error in partition %s: %s%n",
47            errorContext.getPartitionContext().getPartitionId(),
48            errorContext.getThrowable().getMessage());
49    })
50    .buildEventProcessorClient();
51 
52eventProcessorClient.start();
53```
54 
55> ⚠️ **Warning:** Add dependency `com.azure:azure-messaging-eventhubs-checkpointstore-blob` to the project when using `BlobCheckpointStore`.
56 
57### EventProcessorHost with Azure Storage checkpoint/lease
58 
59Legacy code using the built-in storage-backed checkpoint/lease:
60```java
61EventProcessorHost host = EventProcessorHost.EventProcessorHostBuilder
62    .newBuilder(hostName, consumerGroupName)
63    .useAzureStorageCheckpointLeaseManager(storageConnectionString, storageContainerName, null)
64    .useEventHubConnectionString(eventHubConnectionString, eventHubName)
65    .build();
66host.registerEventProcessor(MyEventProcessor.class).get();
67```
68 
69Migrated code:
70```java
71BlobContainerAsyncClient blobContainerClient = new BlobContainerClientBuilder()
72    .connectionString(storageConnectionString)
73    .containerName(storageContainerName)
74    .buildAsyncClient();
75 
76EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()
77    .connectionString(eventHubConnectionString, eventHubName)
78    .consumerGroup(consumerGroupName)
79    .checkpointStore(new BlobCheckpointStore(blobContainerClient))
80    .processEvent(eventContext -> {
81        // Process event and checkpoint
82        eventContext.updateCheckpoint();
83    })
84    .processError(errorContext -> {
85        System.err.printf("Error in partition %s: %s%n",
86            errorContext.getPartitionContext().getPartitionId(),
87            errorContext.getThrowable().getMessage());
88    })
89    .buildEventProcessorClient();
90 
91eventProcessorClient.start();
92```
93 
94### Required imports for migrated code
95 
96```java
97import com.azure.messaging.eventhubs.EventProcessorClient;
98import com.azure.messaging.eventhubs.EventProcessorClientBuilder;
99import com.azure.messaging.eventhubs.checkpointstore.blob.BlobCheckpointStore;
100import com.azure.storage.blob.BlobContainerAsyncClient;
101import com.azure.storage.blob.BlobContainerClientBuilder;
102```
103 
104### Required dependencies
105 
106Add these dependencies when migrating from `com.microsoft.azure:azure-eventhubs-eph`:
107 
108| Legacy Artifact | Modern Artifact |
109|---|---|
110| `com.microsoft.azure:azure-eventhubs-eph` | `com.azure:azure-messaging-eventhubs` |
111| (included in above) | `com.azure:azure-messaging-eventhubs-checkpointstore-blob` |
112