refactor!: java materialization interface rework (#170)

Co-authored-by: Nicklas Lundin <nicklasl@spotify.com>

Author: andreas-karlsson

openfeature-provider/java/README.md

@@ -152,28 +152,32 @@ This is particularly useful for:
 - **Production customization**: Custom TLS settings, proxies, or connection pooling
 - **Debugging**: Add custom logging or tracing interceptors
 
-## Sticky Assignments
+## Materializations
 
-The provider supports **Sticky Assignments** for consistent variant assignments across flag evaluations. This ensures users receive the same variant even when their targeting attributes change, and enables pausing experiment intake.
+The provider supports **materializations** for two key use cases:
 
+1. **Sticky Assignments**: Maintain consistent variant assignments across evaluations even when targeting attributes change. This enables pausing intake (stopping new users from entering an experiment) while keeping existing users in their assigned variants.
 **📖 See the [Integration Guide: Sticky Assignments](../INTEGRATION_GUIDE.md#sticky-assignments)** for how sticky assignments work and their benefits.
 
-**By default, sticky assignments are managed by Confidence servers.** When sticky assignment data is needed, the provider makes a network call to Confidence, which maintains the sticky repository server-side with automatic 90-day TTL management. This requires no additional setup.
+1. **Custom Targeting via Materialized Segments**: Efficiently target precomputed sets of identifiers from datasets. Instead of evaluating complex targeting rules at runtime, materializations allow for fast lookups of whether a unit (user, session, etc.) is included in a target segment.
+
+**By default, materializations are managed by Confidence servers.** When sticky assignment data is needed, the provider makes a network call to Confidence, which maintains the sticky repository server-side with automatic 90-day TTL management. This requires no additional setup.
 
 ### Custom Materialization Storage
 
-Optionally, you can implement a custom `MaterializationRepository` to manage sticky assignments in your own storage (Redis, database, etc.) to eliminate network calls and improve latency:
+Optionally, you can implement a custom `MaterializationStore` to manage materialization data in your own storage (Redis, database, etc.) to eliminate network calls and improve latency:
 
 ```java
-// Optional: Custom storage for sticky assignments
-MaterializationRepository repository = new RedisMaterializationRepository(jedisPool, "myapp");
+// Optional: Custom storage for materialization data
+MaterializationStore store = new RedisMaterializationStore(jedisPool);
 OpenFeatureLocalResolveProvider provider = new OpenFeatureLocalResolveProvider(
     clientSecret,
-    repository
+    store
 );
 ```
 
 For detailed information on how to implement custom storage backends, see [STICKY_RESOLVE.md](STICKY_RESOLVE.md).
+See the `InMemoryMaterializationStoreExample` class in the test sources for a reference implementation, or review the `MaterializationStore` javadoc for detailed API documentation.
 
 ## Requirements
 

openfeature-provider/java/STICKY_RESOLVE.md

@@ -1,89 +1,129 @@
-# Sticky Resolve Documentation
+# Materialization Store Documentation
 
 ## Overview
 
-Sticky Resolve ensures users receive the same variant throughout an experiment, even if their targeting attributes change or you pause new assignments.
+The Materialization Store provides persistent storage for flag resolution data, supporting two key use cases:
 
-**Two main use cases:**
-1. **Consistent experience** - User moves countries but keeps the same variant
-2. **Pause intake** - Stop new assignments while maintaining existing ones
+1. **Sticky Assignments** - Maintain consistent variant assignments across evaluations even when targeting attributes change. This enables pausing intake (stopping new users from entering an experiment) while keeping existing users in their assigned variants.
 
-**Default behavior:** Sticky assignments are managed by Confidence servers with automatic 90-day TTL. When needed, the provider makes a network call to Confidence. No setup required.
+2. **Custom Targeting via Materialized Segments** - Precomputed sets of identifiers from datasets that should be targeted. Instead of evaluating complex targeting rules at runtime, materializations allow efficient lookup of whether a unit (user, session, etc.) is included in a target segment.
+
+**Default behavior:** Materializations are managed by Confidence servers with automatic 90-day TTL. When needed, the provider makes a network call to Confidence. No setup required.
 
 ## How It Works
 
-### Default: Server-Side Storage (RemoteResolverFallback)
+### Default: Server-Side Storage (UnsupportedMaterializationStore)
 
 **Flow:**
 1. Local WASM resolver attempts to resolve
-2. If sticky data needed → network call to Confidence
-3. Confidence checks its sticky repository, returns variant
-4. Assignment stored server-side with 90-day TTL (auto-renewed on access)
+2. If materialization data needed → `UnsupportedMaterializationStore` throws exception
+3. Provider falls back to remote gRPC resolution via Confidence
+4. Confidence checks its materialization repository, returns variant/inclusion data
+5. Data stored server-side with 90-day TTL (auto-renewed on access)
 
 **Server-side configuration (in Confidence UI):**
 - Optionally skip targeting criteria for sticky assignments
 - Pause/resume new entity intake
 - Automatic TTL management
 
-### Custom: Local Storage (MaterializationRepository)
+### Custom: Local Storage (MaterializationStore)
 
-Implement `MaterializationRepository` to store assignments locally and eliminate network calls.
+Implement `MaterializationStore` to store materialization data locally and eliminate network calls.
 
 **Interface:**
 ```java
-public interface MaterializationRepository extends StickyResolveStrategy {
-  // Load assignments for a unit (e.g., user ID)
-  CompletableFuture<Map<String, MaterializationInfo>> loadMaterializedAssignmentsForUnit(
-      String unit, String materialization);
-
-  // Store new assignments
-  CompletableFuture<Void> storeAssignment(
-      String unit, Map<String, MaterializationInfo> assignments);
+public interface MaterializationStore {
+  // Batch read of materialization data
+  CompletionStage<List<ReadResult>> read(List<? extends ReadOp> ops);
+
+  // Batch write of materialization data (optional)
+  default CompletionStage<Void> write(Set<? extends WriteOp> ops) {
+    throw new UnsupportedOperationException("Unimplemented method 'write'");
+  }
+}
+```
+
+**Key Concepts:**
+- **Materialization** - Identifier for a materialization context (experiment, flag, or materialized segment)
+- **Unit** - Entity identifier (user ID, session ID, etc.)
+- **Rule** - Targeting rule identifier within a flag
+- **Variant** - Assigned variant name for the unit+rule combination
+
+**Operation Types:**
+
+Read operations (`ReadOp`):
+```java
+// Check if unit is in materialized segment
+sealed interface ReadOp {
+  record Inclusion(String materialization, String unit) implements ReadOp {}
+  record Variant(String materialization, String unit, String rule) implements ReadOp {}
+}
+```
+
+Read results (`ReadResult`):
+```java
+sealed interface ReadResult {
+  // Result for segment membership check
+  record Inclusion(String materialization, String unit, boolean included) implements ReadResult {}
+
+  // Result for sticky variant assignment
+  record Variant(String materialization, String unit, String rule, Optional<String> variant)
+      implements ReadResult {}
 }
 ```
 
-**MaterializationInfo structure:**
+Write operations (`WriteOp`):
 ```java
-record MaterializationInfo(
-    boolean isUnitInMaterialization,
-    Map<String, String> ruleToVariant  // rule ID -> variant name
-)
+sealed interface WriteOp {
+  // Store sticky variant assignment
+  record Variant(String materialization, String unit, String rule, String variant)
+      implements WriteOp {}
+}
 ```
 
 ## Implementation Examples
 
-### In-Memory (Testing/Development)
+### In-Memory (Testing/Development Only)
+
+**Warning: Do not use in-memory storage in production.** In-memory implementations lose all materialization data on restart, breaking sticky assignments and materialized segments. Production systems require persistent storage (Redis, database, etc.).
 
-[Here is an example](src/test/java/com/spotify/confidence/InMemoryMaterializationRepoExample.java) on how to implement a simple in-memory `MaterializationRepository`. The same approach can be used with other more persistent storages (like Redis or similar) which is highly recommended for production use cases. 
+See `InMemoryMaterializationStoreExample` for a reference implementation. Use this pattern with persistent storage backends for production.
 
 #### Usage
 
 ```java
-MaterializationRepository repository = new InMemoryMaterializationRepoExample();
+MaterializationStore store = new InMemoryMaterializationStore();
 
 OpenFeatureLocalResolveProvider provider = new OpenFeatureLocalResolveProvider(
     clientSecret,
-    repository
+    store
 );
 ```
 
 ## Best Practices
 
-1. **Fail gracefully** - Storage errors shouldn't fail flag resolution
-2. **Use 90-day TTL** - Match Confidence's default behavior, renew on read
-3. **Connection pooling** - Use pools for Redis/DB connections
-4. **Monitor metrics** - Track cache hit rate, storage latency, errors
-5. **Test both paths** - Missing assignments (cold start) and existing assignments
+1. **Thread-safe implementation** - Implementations must be thread-safe for concurrent flag resolution
+2. **Fail gracefully** - Storage errors shouldn't fail flag resolution; throw `MaterializationNotSupportedException` to trigger remote fallback
+3. **Use 90-day TTL** - Match Confidence's default behavior, renew on read
+4. **Idempotent writes** - Write operations should be idempotent
+5. **Batch operations** - Both `read` and `write` accept batches for efficiency
+6. **Connection pooling** - Use pools for Redis/DB connections
+7. **Monitor metrics** - Track cache hit rate, storage latency, errors
+8. **Test both paths** - Missing assignments (cold start) and existing assignments
 
 ## When to Use Custom Storage
 
-| Strategy | Best For | Trade-offs |
+| Implementation | Best For | Trade-offs |
 |----------|----------|------------|
-| **RemoteResolverFallback** (default) | Most apps | Simple, managed by Confidence. Network calls when needed. |
-| **MaterializationRepository** (in-memory) | Single-instance apps, testing | Fast, no network. Lost on restart. |
-| **MaterializationRepository** (Redis/DB) | Distributed/Multi instance apps | No network calls. Requires storage infra. |
+| **UnsupportedMaterializationStore** (default) | Most apps | Simple, managed by Confidence. Network calls when needed. |
+| **MaterializationStore** (in-memory) | Testing/development only | Fast, no network. **Lost on restart - do not use in production.** |
+| **MaterializationStore** (Redis/DB) | Production apps needing local storage | No network calls. Requires persistent storage infrastructure. |
+
+**Start with the default.** Only implement custom storage with persistent backends (Redis, database) if you need to eliminate network calls or work offline.
+
+## Error Handling
 
-**Start with the default.** Only implement custom storage if you need to eliminate network calls or work offline.
+When implementing `read()`, throw `MaterializationNotSupportedException` to trigger fallback to remote gRPC resolution. This allows graceful degradation when local storage is unavailable.
 
 ## Additional Resources
 

openfeature-provider/java/src/main/java/com/spotify/confidence/ConfidenceGrpcFlagResolver.java

@@ -1,25 +1,18 @@
 package com.spotify.confidence;
 
-import com.google.protobuf.Struct;
 import com.spotify.confidence.flags.resolver.v1.FlagResolverServiceGrpc;
 import com.spotify.confidence.flags.resolver.v1.ResolveFlagsRequest;
 import com.spotify.confidence.flags.resolver.v1.ResolveFlagsResponse;
-import com.spotify.confidence.flags.resolver.v1.Sdk;
-import com.spotify.confidence.flags.resolver.v1.Sdk.Builder;
-import com.spotify.confidence.flags.resolver.v1.SdkId;
 import io.grpc.ManagedChannel;
-import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
 
 /**
  * A simplified gRPC-based flag resolver for fallback scenarios in the local provider. This is a
  * copy of the core functionality from GrpcFlagResolver adapted for the local provider's needs.
  */
-public class ConfidenceGrpcFlagResolver {
+public class ConfidenceGrpcFlagResolver implements RemoteResolver {
   private final ManagedChannel channel;
-  private final Builder sdkBuilder =
-      Sdk.newBuilder().setVersion("0.2.8"); // Using static version for local provider
 
   private final FlagResolverServiceGrpc.FlagResolverServiceFutureStub stub;
 
@@ -28,20 +21,13 @@ public ConfidenceGrpcFlagResolver(ChannelFactory channelFactory) {
     this.stub = FlagResolverServiceGrpc.newFutureStub(channel);
   }
 
-  public CompletableFuture<ResolveFlagsResponse> resolve(
-      List<String> flags, String clientSecret, Struct context) {
+  @Override
+  public CompletableFuture<ResolveFlagsResponse> resolve(ResolveFlagsRequest request) {
     return GrpcUtil.toCompletableFuture(
-        stub.withDeadlineAfter(10_000, TimeUnit.MILLISECONDS)
-            .resolveFlags(
-                ResolveFlagsRequest.newBuilder()
-                    .setClientSecret(clientSecret)
-                    .addAllFlags(flags)
-                    .setEvaluationContext(context)
-                    .setSdk(sdkBuilder.setId(SdkId.SDK_ID_JAVA_PROVIDER).build())
-                    .setApply(true)
-                    .build()));
+        stub.withDeadlineAfter(10_000, TimeUnit.MILLISECONDS).resolveFlags(request));
   }
 
+  @Override
   public void close() {
     channel.shutdownNow();
   }

openfeature-provider/java/src/main/java/com/spotify/confidence/MaterializationInfo.java

@@ -0,0 +1,15 @@
+package com.spotify.confidence;
+
+/**
+ * Thrown when a {@link MaterializationStore} doesn't support the requested operation.
+ *
+ * <p>This exception triggers the provider to fall back to remote gRPC resolution via the Confidence
+ * service, which manages materializations server-side.
+ *
+ * <p>Users typically don't need to catch this exception - it's handled internally by the provider's
+ * resolution logic.
+ *
+ * @see UnsupportedMaterializationStore
+ * @see MaterializationStore
+ */
+public class MaterializationNotSupportedException extends RuntimeException {}