Add predicate-aware informer event handlers

e2e/src/test/java/io/kubernetes/client/e2e/informer/NamespaceInformerTest.java

@@ -17,12 +17,18 @@
 
 import io.kubernetes.client.informer.SharedIndexInformer;
 import io.kubernetes.client.informer.SharedInformerFactory;
+import io.kubernetes.client.informer.ResourceEventHandler;
 import io.kubernetes.client.informer.cache.Lister;
 import io.kubernetes.client.openapi.ApiClient;
+import io.kubernetes.client.openapi.apis.CoreV1Api;
 import io.kubernetes.client.openapi.models.V1Namespace;
 import io.kubernetes.client.openapi.models.V1NamespaceList;
+import io.kubernetes.client.openapi.models.V1ObjectMeta;
 import io.kubernetes.client.util.ClientBuilder;
 import io.kubernetes.client.util.generic.GenericKubernetesApi;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
 import org.junit.jupiter.api.Test;
 
 class NamespaceInformerTest {
@@ -57,4 +63,59 @@ void listWatchingNamespaces() throws Exception {
       informerFactory.stopAllRegisteredInformers(true);
     }
   }
+
+  @Test
+  void listWatchingNamespacesWithPredicateHandler() throws Exception {
+    ApiClient client = ClientBuilder.defaultClient();
+    CoreV1Api coreV1Api = new CoreV1Api(client);
+    SharedInformerFactory informerFactory = new SharedInformerFactory(client);
+    String selectedNamespace = "e2e-filtered-selected";
+    String ignoredNamespace = "e2e-filtered-ignored";
+
+    coreV1Api.createNamespace(new V1Namespace().metadata(new V1ObjectMeta().name(selectedNamespace))).execute();
+    coreV1Api.createNamespace(new V1Namespace().metadata(new V1ObjectMeta().name(ignoredNamespace))).execute();
+
+    GenericKubernetesApi<V1Namespace, V1NamespaceList> api =
+        new GenericKubernetesApi<>(V1Namespace.class, V1NamespaceList.class, "", "v1", "namespaces", client);
+
+    SharedIndexInformer<V1Namespace> nsInformer =
+        informerFactory.sharedIndexInformerFor(api, V1Namespace.class, 0);
+    CountDownLatch selectedSeen = new CountDownLatch(1);
+    AtomicBoolean ignoredSeen = new AtomicBoolean(false);
+    AtomicBoolean selectedSeenByHandler = new AtomicBoolean(false);
+    try {
+      nsInformer.addEventHandler(
+          new ResourceEventHandler<V1Namespace>() {
+            @Override
+            public void onAdd(V1Namespace obj) {
+              String name = obj.getMetadata().getName();
+              if (selectedNamespace.equals(name)) {
+                selectedSeenByHandler.set(true);
+                selectedSeen.countDown();
+              }
+              if (ignoredNamespace.equals(name)) {
+                ignoredSeen.set(true);
+              }
+            }
+
+            @Override
+            public void onUpdate(V1Namespace oldObj, V1Namespace newObj) {}
+
+            @Override
+            public void onDelete(V1Namespace obj, boolean deletedFinalStateUnknown) {}
+          },
+          ns -> selectedNamespace.equals(ns.getMetadata().getName()));
+
+      informerFactory.startAllRegisteredInformers();
+
+      await().untilAsserted(() -> assertThat(nsInformer.hasSynced()).isTrue());
+      assertThat(selectedSeen.await(30, TimeUnit.SECONDS)).isTrue();
+      assertThat(selectedSeenByHandler.get()).isTrue();
+      assertThat(ignoredSeen.get()).isFalse();
+    } finally {
+      informerFactory.stopAllRegisteredInformers(true);
+      coreV1Api.deleteNamespace(selectedNamespace).execute();
+      coreV1Api.deleteNamespace(ignoredNamespace).execute();
+    }
+  }
 }

util/src/main/java/io/kubernetes/client/informer/FilteringResourceEventHandler.java

@@ -0,0 +1,80 @@
+/*
+Copyright 2026 The Kubernetes Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package io.kubernetes.client.informer;
+
+import io.kubernetes.client.common.KubernetesObject;
+import java.util.Objects;
+import java.util.function.Predicate;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * FilteringResourceEventHandler dispatches events only when objects match a predicate.
+ */
+public class FilteringResourceEventHandler<ApiType extends KubernetesObject>
+    implements ResourceEventHandler<ApiType> {
+
+  private static final Logger log = LoggerFactory.getLogger(FilteringResourceEventHandler.class);
+
+  private final ResourceEventHandler<ApiType> delegate;
+  private final Predicate<ApiType> filter;
+
+  public FilteringResourceEventHandler(
+      ResourceEventHandler<ApiType> delegate, Predicate<ApiType> filter) {
+    this.delegate = Objects.requireNonNull(delegate);
+    this.filter = Objects.requireNonNull(filter);
+  }
+
+  @Override
+  public void onAdd(ApiType obj) {
+    if (matches(obj)) {
+      delegate.onAdd(obj);
+    }
+  }
+
+  @Override
+  public void onUpdate(ApiType oldObj, ApiType newObj) {
+    boolean oldMatched = matches(oldObj);
+    boolean newMatched = matches(newObj);
+    if (oldMatched && newMatched) {
+      delegate.onUpdate(oldObj, newObj);
+      return;
+    }
+    if (!oldMatched && newMatched) {
+      delegate.onAdd(newObj);
+      return;
+    }
+    if (oldMatched) {
+      delegate.onDelete(oldObj, false);
+    }
+  }
+
+  @Override
+  public void onDelete(ApiType obj, boolean deletedFinalStateUnknown) {
+    if (matches(obj)) {
+      delegate.onDelete(obj, deletedFinalStateUnknown);
+    }
+  }
+
+  private boolean matches(ApiType obj) {
+    if (obj == null) {
+      return false;
+    }
+    try {
+      return filter.test(obj);
+    } catch (RuntimeException e) {
+      log.warn("Predicate threw an exception; dropping informer event", e);
+      return false;
+    }
+  }
+}

util/src/main/java/io/kubernetes/client/informer/SharedInformer.java

@@ -13,6 +13,7 @@
 package io.kubernetes.client.informer;
 
 import io.kubernetes.client.common.KubernetesObject;
+import java.util.function.Predicate;
 
 /*
  * SharedInformer defines basic methods of a informer.
@@ -26,6 +27,14 @@ public interface SharedInformer<ApiType extends KubernetesObject> {
    */
   void addEventHandler(ResourceEventHandler<ApiType> handler);
 
+  /**
+   * Add event handler with predicate filter.
+   *
+   * @param handler the handler
+   * @param filter the object filter
+   */
+  void addEventHandler(ResourceEventHandler<ApiType> handler, Predicate<ApiType> filter);
+
   /**
    * addEventHandlerWithResyncPeriod adds an event handler to the shared informer using the
    * specified resync period. Events to a single handler are delivered sequentially, but there is no
@@ -36,6 +45,17 @@ public interface SharedInformer<ApiType extends KubernetesObject> {
    */
   void addEventHandlerWithResyncPeriod(ResourceEventHandler<ApiType> handler, long resyncPeriod);
 
+  /**
+   * addEventHandlerWithResyncPeriod adds an event handler with the specified resync period and
+   * object filter.
+   *
+   * @param handler the event handler
+   * @param resyncPeriod the specific resync period
+   * @param filter the object filter
+   */
+  void addEventHandlerWithResyncPeriod(
+      ResourceEventHandler<ApiType> handler, long resyncPeriod, Predicate<ApiType> filter);
+
   /** run starts the shared informer, which will be stopped until stop() is called. */
   void run();
 

util/src/main/java/io/kubernetes/client/informer/impl/DefaultSharedIndexInformer.java

@@ -18,6 +18,7 @@
 import io.kubernetes.client.informer.ResourceEventHandler;
 import io.kubernetes.client.informer.SharedIndexInformer;
 import io.kubernetes.client.informer.TransformFunc;
+import io.kubernetes.client.informer.FilteringResourceEventHandler;
 import io.kubernetes.client.informer.cache.Cache;
 import io.kubernetes.client.informer.cache.Controller;
 import io.kubernetes.client.informer.cache.DeltaFIFO;
@@ -31,6 +32,7 @@
 import java.util.concurrent.ThreadFactory;
 import java.util.function.BiConsumer;
 import java.util.function.Function;
+import java.util.function.Predicate;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.tuple.MutablePair;
 import org.slf4j.Logger;
@@ -152,13 +154,27 @@ public DefaultSharedIndexInformer(
   /** add event callback */
   @Override
   public void addEventHandler(ResourceEventHandler<ApiType> handler) {
-    addEventHandlerWithResyncPeriod(handler, defaultEventHandlerResyncPeriod);
+    addEventHandler(handler, obj -> true);
+  }
+
+  @Override
+  public void addEventHandler(
+      ResourceEventHandler<ApiType> handler, Predicate<ApiType> filterPredicate) {
+    addEventHandlerWithResyncPeriod(handler, defaultEventHandlerResyncPeriod, filterPredicate);
   }
 
   /** add event callback with a resync period */
   @Override
   public void addEventHandlerWithResyncPeriod(
       ResourceEventHandler<ApiType> handler, long resyncPeriodMillis) {
+    addEventHandlerWithResyncPeriod(handler, resyncPeriodMillis, obj -> true);
+  }
+
+  @Override
+  public void addEventHandlerWithResyncPeriod(
+      ResourceEventHandler<ApiType> handler,
+      long resyncPeriodMillis,
+      Predicate<ApiType> filterPredicate) {
     if (stopped) {
       log.info(
           "DefaultSharedIndexInformer#Handler was not added to shared informer because it has stopped already");
@@ -195,7 +211,8 @@ public void addEventHandlerWithResyncPeriod(
 
     ProcessorListener<ApiType> listener =
         new ProcessorListener(
-            handler, determineResyncPeriod(resyncCheckPeriodMillis, this.resyncCheckPeriodMillis));
+            new FilteringResourceEventHandler<>(handler, filterPredicate),
+            determineResyncPeriod(resyncCheckPeriodMillis, this.resyncCheckPeriodMillis));
     if (!started) {
       this.processor.addListener(listener);
       return;

util/src/test/java/io/kubernetes/client/informer/FilteringResourceEventHandlerTest.java

@@ -0,0 +1,107 @@
+/*
+Copyright 2026 The Kubernetes Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package io.kubernetes.client.informer;
+
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+
+import io.kubernetes.client.openapi.models.V1ObjectMeta;
+import io.kubernetes.client.openapi.models.V1Pod;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+class FilteringResourceEventHandlerTest {
+
+  private static V1Pod pod(String name) {
+    return new V1Pod().metadata(new V1ObjectMeta().namespace("default").name(name));
+  }
+
+  @Test
+  void dropsAddForFilteredOutObject() {
+    ResourceEventHandler<V1Pod> delegate = Mockito.mock(ResourceEventHandler.class);
+    FilteringResourceEventHandler<V1Pod> handler =
+        new FilteringResourceEventHandler<>(delegate, obj -> "selected".equals(obj.getMetadata().getName()));
+
+    handler.onAdd(pod("ignored"));
+
+    verifyNoInteractions(delegate);
+  }
+
+  @Test
+  void convertsUpdateTransitionIntoAdd() {
+    ResourceEventHandler<V1Pod> delegate = Mockito.mock(ResourceEventHandler.class);
+    FilteringResourceEventHandler<V1Pod> handler =
+        new FilteringResourceEventHandler<>(delegate, obj -> "selected".equals(obj.getMetadata().getName()));
+    V1Pod oldObj = pod("ignored");
+    V1Pod newObj = pod("selected");
+
+    handler.onUpdate(oldObj, newObj);
+
+    verify(delegate).onAdd(newObj);
+    verify(delegate, never()).onUpdate(oldObj, newObj);
+    verify(delegate, never()).onDelete(oldObj, false);
+  }
+
+  @Test
+  void convertsUpdateTransitionIntoDelete() {
+    ResourceEventHandler<V1Pod> delegate = Mockito.mock(ResourceEventHandler.class);
+    FilteringResourceEventHandler<V1Pod> handler =
+        new FilteringResourceEventHandler<>(delegate, obj -> "selected".equals(obj.getMetadata().getName()));
+    V1Pod oldObj = pod("selected");
+    V1Pod newObj = pod("ignored");
+
+    handler.onUpdate(oldObj, newObj);
+
+    verify(delegate).onDelete(oldObj, false);
+    verify(delegate, never()).onUpdate(oldObj, newObj);
+    verify(delegate, never()).onAdd(newObj);
+  }
+
+  @Test
+  void preservesUpdateWhenOldAndNewMatch() {
+    ResourceEventHandler<V1Pod> delegate = Mockito.mock(ResourceEventHandler.class);
+    FilteringResourceEventHandler<V1Pod> handler =
+        new FilteringResourceEventHandler<>(delegate, obj -> "selected".equals(obj.getMetadata().getName()));
+    V1Pod oldObj = pod("selected");
+    V1Pod newObj = pod("selected");
+
+    handler.onUpdate(oldObj, newObj);
+
+    verify(delegate).onUpdate(oldObj, newObj);
+    verify(delegate, never()).onAdd(newObj);
+    verify(delegate, never()).onDelete(oldObj, false);
+  }
+
+  @Test
+  void dropsDeleteForFilteredOutObject() {
+    ResourceEventHandler<V1Pod> delegate = Mockito.mock(ResourceEventHandler.class);
+    FilteringResourceEventHandler<V1Pod> handler =
+        new FilteringResourceEventHandler<>(delegate, obj -> "selected".equals(obj.getMetadata().getName()));
+
+    handler.onDelete(pod("ignored"), false);
+
+    verifyNoInteractions(delegate);
+  }
+
+  @Test
+  void shouldIgnoreDeleteWhenPredicateThrows() {
+    ResourceEventHandler<V1Pod> delegate = Mockito.mock(ResourceEventHandler.class);
+    FilteringResourceEventHandler<V1Pod> handler =
+        new FilteringResourceEventHandler<>(delegate, obj -> "selected".equals(obj.getMetadata().getName()));
+
+    handler.onDelete(new V1Pod(), true);
+
+    verifyNoInteractions(delegate);
+  }
+}