New methods for SplitEventTask

api/src/main/java/io/split/android/client/events/SplitEventTask.java

@@ -1,17 +1,113 @@
 package io.split.android.client.events;
 
+import androidx.annotation.Nullable;
+
 import io.split.android.client.SplitClient;
+import io.split.android.client.api.EventMetadata;
 
 /**
- * Created by sarrubia on 3/26/18.
+ * Base class for handling Split SDK events.
+ * <p>
+ * Extend this class and override the methods you need to handle specific SDK events.
+ * You can implement both the metadata-enabled and versions of the methods;
+ * if both are implemented, both will be called (metadata version first).
+ * <p>
+ * <b>Threading:</b>
+ * <ul>
+ *   <li>{@code onPostExecution} methods are called on a background thread (faster, executed immediately)</li>
+ *   <li>{@code onPostExecutionView} methods are called on the main/UI thread (queued on main looper)</li>
+ * </ul>
+ * <p>
+ * <b>Metadata:</b>
+ * <ul>
+ *   <li>Metadata-enabled methods receive {@link EventMetadata} containing event-specific information</li>
+ *   <li>Metadata may be {@code null} for some events</li>
+ *   <li>If you only need metadata, implement the metadata version; if you need backward compatibility,
+ *       implement both versions</li>
+ * </ul>
+ * <p>
+ * Example usage:
+ * <pre>{@code
+ * client.on(SplitEvent.SDK_UPDATE, new SplitEventTask() {
+ *     @Override
+ *     public void onPostExecution(SplitClient client, EventMetadata metadata) {
+ *         List<String> updatedFlags = (List<String>) metadata.get("updatedFlags");
+ *         // Handle update with metadata
+ *     }
+ *
+ *     @Override
+ *     public void onPostExecution(SplitClient client) {
+ *         // Legacy handling (also called if both are implemented)
+ *     }
+ * });
+ * }</pre>
  */
-
 public class SplitEventTask {
+    /**
+     * Called when an event occurs, executed on a background thread.
+     * <p>
+     * Override this method to handle events on a background thread without metadata.
+     * This method is executed immediately and is faster than {@link #onPostExecutionView(SplitClient)}.
+     *
+     * @param client the Split client instance
+     * @throws SplitEventTaskMethodNotImplementedException if not overridden (default behavior)
+     */
     public void onPostExecution(SplitClient client) {
         throw new SplitEventTaskMethodNotImplementedException();
     }
 
+    /**
+     * Called when an event occurs, executed on the main/UI thread.
+     * <p>
+     * Override this method to handle events on the main thread without metadata.
+     * Use this when you need to update UI components.
+     * <p>
+     * Note: This method is queued on the main looper, so execution may be delayed
+     * compared to {@link #onPostExecution(SplitClient)}.
+     *
+     * @param client the Split client instance
+     * @throws SplitEventTaskMethodNotImplementedException if not overridden (default behavior)
+     */
     public void onPostExecutionView(SplitClient client) {
         throw new SplitEventTaskMethodNotImplementedException();
     }
+
+    /**
+     * Called when an event occurs with metadata, executed on a background thread.
+     * <p>
+     * Override this method to handle events on a background thread with access to event metadata.
+     * The metadata contains event-specific information such as updated flag names for SDK_UPDATE events.
+     * This method is executed immediately and is faster than {@link #onPostExecutionView(SplitClient, EventMetadata)}.
+     * <p>
+     * If both this method and {@link #onPostExecution(SplitClient)} are implemented,
+     * both will be called (this method first).
+     *
+     * @param client   the Split client instance
+     * @param metadata the event metadata, may be {@code null} for some events
+     * @throws SplitEventTaskMethodNotImplementedException if not overridden (default behavior)
+     */
+    public void onPostExecution(SplitClient client, @Nullable EventMetadata metadata) {
+        throw new SplitEventTaskMethodNotImplementedException();
+    }
+
+    /**
+     * Called when an event occurs with metadata, executed on the main/UI thread.
+     * <p>
+     * Override this method to handle events on the main thread with access to event metadata.
+     * The metadata contains event-specific information such as updated flag names for SDK_UPDATE events.
+     * Use this when you need to update UI components based on event metadata.
+     * <p>
+     * Note: This method is queued on the main looper, so execution may be delayed
+     * compared to {@link #onPostExecution(SplitClient, EventMetadata)}.
+     * <p>
+     * If both this method and {@link #onPostExecutionView(SplitClient)} are implemented,
+     * both will be called (this method first).
+     *
+     * @param client   the Split client instance
+     * @param metadata the event metadata, may be {@code null} for some events
+     * @throws SplitEventTaskMethodNotImplementedException if not overridden (default behavior)
+     */
+    public void onPostExecutionView(SplitClient client, @Nullable EventMetadata metadata) {
+        throw new SplitEventTaskMethodNotImplementedException();
+    }
 }

events-domain/src/main/java/io/split/android/client/events/SplitEventsManager.java

@@ -145,30 +145,66 @@ public void run() {
     }
 
     private EventHandler<SplitEvent, EventMetadata> createBackgroundHandler(final SplitEventTask task) {
-        return new EventHandler<SplitEvent, EventMetadata>() {
+        return createEventHandler(task, "background", new TaskMethodCaller() {
             @Override
-            public void handle(SplitEvent event, EventMetadata metadata) {
-                try {
-                    task.onPostExecution(mResources.getSplitClient());
-                } catch (SplitEventTaskMethodNotImplementedException e) {
-                    // Method not implemented by client, ignore
-                } catch (Exception e) {
-                    Logger.e("Error executing background event task: " + e.getMessage());
-                }
+            public void callWithMetadata(EventMetadata metadata) {
+                task.onPostExecution(mResources.getSplitClient(), metadata);
             }
-        };
+
+            @Override
+            public void callWithoutMetadata() {
+                task.onPostExecution(mResources.getSplitClient());
+            }
+        });
     }
 
     private EventHandler<SplitEvent, EventMetadata> createMainThreadHandler(final SplitEventTask task) {
+        return createEventHandler(task, "main thread", new TaskMethodCaller() {
+            @Override
+            public void callWithMetadata(EventMetadata metadata) {
+                task.onPostExecutionView(mResources.getSplitClient(), metadata);
+            }
+
+            @Override
+            public void callWithoutMetadata() {
+                task.onPostExecutionView(mResources.getSplitClient());
+            }
+        });
+    }
+
+    /**
+     * Helper interface for calling task methods.
+     */
+    private interface TaskMethodCaller {
+        void callWithMetadata(EventMetadata metadata) throws Exception;
+        void callWithoutMetadata() throws Exception;
+    }
+
+    private EventHandler<SplitEvent, EventMetadata> createEventHandler(
+            final SplitEventTask task,
+            final String threadType,
+            final TaskMethodCaller caller) {
         return new EventHandler<SplitEvent, EventMetadata>() {
             @Override
             public void handle(SplitEvent event, EventMetadata metadata) {
+                executeTaskMethod(metadata, true, threadType, caller);
+                executeTaskMethod(metadata, false, threadType, caller);
+            }
+
+            private void executeTaskMethod(EventMetadata metadata, boolean withMetadata, String threadType, TaskMethodCaller caller) {
                 try {
-                    task.onPostExecutionView(mResources.getSplitClient());
+                    if (withMetadata) {
+                        caller.callWithMetadata(metadata);
+                    } else {
+                        caller.callWithoutMetadata();
+                    }
                 } catch (SplitEventTaskMethodNotImplementedException e) {
                     // Method not implemented by client, ignore
                 } catch (Exception e) {
-                    Logger.e("Error executing main thread event task: " + e.getMessage());
+                    String errorPrefix = withMetadata
+                            ? "Error executing " + threadType + " event task (with metadata): "
+                            : "Error executing " + threadType + " event task: ";
+                    Logger.e(errorPrefix + e.getMessage());
                 }
             }
         };

main/src/androidTest/java/tests/service/EventsManagerTest.java

@@ -1,17 +1,26 @@
 package tests.service;
 
+import android.os.Looper;
+
 import org.junit.Assert;
 import org.junit.Test;
 
+import java.util.Arrays;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
 
 import fake.SplitEventExecutorResourcesMock;
 import helper.TestingHelper;
+import io.split.android.client.SplitClient;
 import io.split.android.client.SplitClientConfig;
+import io.split.android.client.api.EventMetadata;
 import io.split.android.client.events.SplitEvent;
+import io.split.android.client.events.SplitEventTask;
 import io.split.android.client.events.SplitEventsManager;
 import io.split.android.client.events.SplitInternalEvent;
+import io.split.android.client.events.metadata.EventMetadataHelpers;
 import io.split.android.client.service.executor.SplitTaskExecutorImpl;
 
 public class EventsManagerTest {
@@ -232,4 +241,95 @@ public void testTimeoutMySegmentsUpdated() throws InterruptedException {
         Assert.assertFalse(updateTask.onExecutedCalled);
         Assert.assertTrue(timeoutTask.onExecutedCalled);
     }
+
+    @Test
+    public void testAllFourCallbackMethodsAreCalledWithCorrectThreadContext() throws InterruptedException {
+        SplitClientConfig cfg = SplitClientConfig.builder().build();
+        SplitEventsManager eventManager = new SplitEventsManager(new SplitTaskExecutorImpl(), cfg.blockUntilReady());
+        eventManager.setExecutionResources(new SplitEventExecutorResourcesMock());
+
+        CountDownLatch readyLatch = new CountDownLatch(1);
+        CountDownLatch allCalledLatch = new CountDownLatch(4); // Expect 4 calls
+
+        AtomicBoolean backgroundMetadataCalled = new AtomicBoolean(false);
+        AtomicBoolean backgroundLegacyCalled = new AtomicBoolean(false);
+        AtomicBoolean mainThreadMetadataCalled = new AtomicBoolean(false);
+        AtomicBoolean mainThreadLegacyCalled = new AtomicBoolean(false);
+
+        AtomicBoolean backgroundMetadataOnMainThread = new AtomicBoolean(true); // Should be false
+        AtomicBoolean backgroundLegacyOnMainThread = new AtomicBoolean(true);   // Should be false
+        AtomicBoolean mainThreadMetadataOnMainThread = new AtomicBoolean(false); // Should be true
+        AtomicBoolean mainThreadLegacyOnMainThread = new AtomicBoolean(false);   // Should be true
+
+        AtomicReference<EventMetadata> backgroundMetadata = new AtomicReference<>();
+        AtomicReference<EventMetadata> mainThreadMetadata = new AtomicReference<>();
+
+        // Wait for SDK_READY first
+        eventManager.register(SplitEvent.SDK_READY, new SplitEventTask() {
+            @Override
+            public void onPostExecutionView(SplitClient client) {
+                readyLatch.countDown();
+            }
+        });
+
+        // Register a task that implements ALL FOUR methods
+        eventManager.register(SplitEvent.SDK_UPDATE, new SplitEventTask() {
+            @Override
+            public void onPostExecution(SplitClient client, EventMetadata metadata) {
+                backgroundMetadataCalled.set(true);
+                backgroundMetadataOnMainThread.set(Looper.myLooper() == Looper.getMainLooper());
+                backgroundMetadata.set(metadata);
+                allCalledLatch.countDown();
+            }
+
+            @Override
+            public void onPostExecution(SplitClient client) {
+                backgroundLegacyCalled.set(true);
+                backgroundLegacyOnMainThread.set(Looper.myLooper() == Looper.getMainLooper());
+                allCalledLatch.countDown();
+            }
+
+            @Override
+            public void onPostExecutionView(SplitClient client, EventMetadata metadata) {
+                mainThreadMetadataCalled.set(true);
+                mainThreadMetadataOnMainThread.set(Looper.myLooper() == Looper.getMainLooper());
+                mainThreadMetadata.set(metadata);
+                allCalledLatch.countDown();
+            }
+
+            @Override
+            public void onPostExecutionView(SplitClient client) {
+                mainThreadLegacyCalled.set(true);
+                mainThreadLegacyOnMainThread.set(Looper.myLooper() == Looper.getMainLooper());
+                allCalledLatch.countDown();
+            }
+        });
+
+        // Make SDK_READY fire
+        eventManager.notifyInternalEvent(SplitInternalEvent.TARGETING_RULES_SYNC_COMPLETE);
+        eventManager.notifyInternalEvent(SplitInternalEvent.MEMBERSHIPS_SYNC_COMPLETE);
+        Assert.assertTrue("SDK_READY should fire", readyLatch.await(5, TimeUnit.SECONDS));
+
+        // Trigger SDK_UPDATE with metadata
+        EventMetadata metadata = EventMetadataHelpers.createUpdatedFlagsMetadata(
+                Arrays.asList("flag1", "flag2"));
+        eventManager.notifyInternalEvent(SplitInternalEvent.SPLITS_UPDATED, metadata);
+
+        Assert.assertTrue("All four callbacks should be called", allCalledLatch.await(5, TimeUnit.SECONDS));
+
+        Assert.assertTrue("Background metadata method should be called", backgroundMetadataCalled.get());
+        Assert.assertTrue("Background legacy method should be called", backgroundLegacyCalled.get());
+        Assert.assertTrue("Main thread metadata method should be called", mainThreadMetadataCalled.get());
+        Assert.assertTrue("Main thread legacy method should be called", mainThreadLegacyCalled.get());
+
+        Assert.assertFalse("Background metadata method should NOT run on main thread", backgroundMetadataOnMainThread.get());
+        Assert.assertFalse("Background legacy method should NOT run on main thread", backgroundLegacyOnMainThread.get());
+        Assert.assertTrue("Main thread metadata method SHOULD run on main thread", mainThreadMetadataOnMainThread.get());
+        Assert.assertTrue("Main thread legacy method SHOULD run on main thread", mainThreadLegacyOnMainThread.get());
+
+        Assert.assertNotNull("Background metadata should not be null", backgroundMetadata.get());
+        Assert.assertTrue("Background metadata should contain updatedFlags", backgroundMetadata.get().containsKey("updatedFlags"));
+        Assert.assertNotNull("Main thread metadata should not be null", mainThreadMetadata.get());
+        Assert.assertTrue("Main thread metadata should contain updatedFlags", mainThreadMetadata.get().containsKey("updatedFlags"));
+    }
 }