# 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](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.

Legacy code:
```java
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:
```java
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:
```java
EventProcessorHost host = EventProcessorHost.EventProcessorHostBuilder
    .newBuilder(hostName, consumerGroupName)
    .useAzureStorageCheckpointLeaseManager(storageConnectionString, storageContainerName, null)
    .useEventHubConnectionString(eventHubConnectionString, eventHubName)
    .build();
host.registerEventProcessor(MyEventProcessor.class).get();
```

Migrated code:
```java
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

```java
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`:

| Legacy Artifact | Modern Artifact |
|---|---|
| `com.microsoft.azure:azure-eventhubs-eph` | `com.azure:azure-messaging-eventhubs` |
| (included in above) | `com.azure:azure-messaging-eventhubs-checkpointstore-blob` |