From 496f0eb5eeed1a01adf191cca6a1d79776c76f2d Mon Sep 17 00:00:00 2001
From: jutur <abhinav.reddy1893@gmail.com>
Date: Tue, 16 Jun 2026 21:39:15 -0700
Subject: [PATCH] catalog: add getVersionedPluginCatalog overload accepting a
 planNames hint

Adds a default method that accepts a Set<String> planNames alongside the
existing properties and context parameters. Kill Bill core already knows
which plans are needed during invoice generation (from the billing event
set) and can pass them here so that catalog plugins managing large
catalogs can return a shallow subset rather than the full catalog,
reducing serialization and processing overhead.

The default implementation delegates to the existing full-catalog method,
so existing plugin implementations require no changes.

Fixes killbill/killbill#2258
---
 .../catalog/plugin/api/CatalogPluginApi.java  | 33 ++++++++++++++-----
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/catalog/src/main/java/org/killbill/billing/catalog/plugin/api/CatalogPluginApi.java b/catalog/src/main/java/org/killbill/billing/catalog/plugin/api/CatalogPluginApi.java
index 8488011..530c1ff 100644
--- a/catalog/src/main/java/org/killbill/billing/catalog/plugin/api/CatalogPluginApi.java
+++ b/catalog/src/main/java/org/killbill/billing/catalog/plugin/api/CatalogPluginApi.java
@@ -17,26 +17,41 @@
 
 package org.killbill.billing.catalog.plugin.api;
 
+import java.util.Set;
+
 import org.joda.time.DateTime;
 import org.killbill.billing.payment.api.PluginProperty;
 import org.killbill.billing.util.callcontext.TenantContext;
 
 public interface CatalogPluginApi {
 
+    public DateTime getLatestCatalogVersion(Iterable<PluginProperty> properties, final TenantContext context);
+
     /**
+     * Returns a plugin versioned catalog for this tenant containing all plans.
      *
-     * @param properties
-     * @param context
-     * @return
+     * @param properties plugin properties
+     * @param context    tenant context
+     * @return versioned catalog or null if this plugin does not manage the catalog for this tenant
      */
-    public DateTime getLatestCatalogVersion(Iterable<PluginProperty> properties, final TenantContext context);
-
+    public VersionedPluginCatalog getVersionedPluginCatalog(Iterable<PluginProperty> properties, final TenantContext context);
 
     /**
-     * Returns a plugin versioned catalog for this tenant
+     * Returns a plugin versioned catalog restricted to the specified plan names.
+     * <p>
+     * Kill Bill calls this overload when it already knows which plans are required (e.g. during
+     * invoice generation) so that plugins managing large catalogs can return a shallow subset
+     * rather than the full catalog, reducing serialization and processing overhead.
+     * <p>
+     * Implementations that do not need this optimization may rely on the default, which
+     * delegates to {@link #getVersionedPluginCatalog(Iterable, TenantContext)}.
      *
-     * @param context
-     * @return
+     * @param planNames  the set of plan names Kill Bill needs; never null but may be empty
+     * @param properties plugin properties
+     * @param context    tenant context
+     * @return versioned catalog or null if this plugin does not manage the catalog for this tenant
      */
-    public VersionedPluginCatalog getVersionedPluginCatalog(Iterable<PluginProperty> properties, final TenantContext context);
+    default VersionedPluginCatalog getVersionedPluginCatalog(final Set<String> planNames, final Iterable<PluginProperty> properties, final TenantContext context) {
+        return getVersionedPluginCatalog(properties, context);
+    }
 }