Add Delegator to all API Implementations #2434

adnanhemani · 2025-08-22T20:34:45Z

~~Draft~~ PR of the discussion on the Dev ML regarding using the Delegator pattern to add Events instrumentation to all Polaris APIs.

dimas-b · 2025-08-22T20:43:20Z

runtime/service/src/main/java/org/apache/polaris/service/admin/ApiBusinessLogic.java

+@Qualifier
+@Retention(RUNTIME)
+@Target({TYPE, METHOD, FIELD, PARAMETER})
+public @interface ApiBusinessLogic {


I'm against the term "business logic". I find it very confusing. How about PublicApi?

I'm not sure @PublicApi captures what we're trying to say here. What do you think about something like @ApiBaseImplementation?

I see your idea now, I think 😅

However, I'm not sure this is the best approach. Current delegators tae concrete classes into their constructors - this reduces option for composing the delegators with other implementations.

Since delegation is apparently covering API interfaces, I believe it is best to have one delegator per *ApiService interface.

Then, I propose to use @MainService as a @Qualifier for PolarisServiceImpl, etc.

For completeness, we should probably use a qualifier like @EventsService for delegators that introduce events.

This way, both sets of services can be disambiguated in this repo and in downstream projects.

...e/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceDefaultDelegator.java

dimas-b · 2025-08-22T20:49:28Z

...e/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceDefaultDelegator.java

+
+
+@RequestScoped
+@Alternative


What do we achieve by always using these delegating wrappers?

Once we get these delegating wrappers in, we can start adding the events instrumentation to these wrappers (as discussed on the Dev ML, based on the feedback from the community).

For example, the code in #1904 would then be re-written to go into these delegator classes instead.

Should we have something like PolarisServiceWithEvents?.. or EventProducingPolarisService?

The impl. will follow the delegator pattern. It's the "Default Delegator" in the class name that make me confused.

adnanhemani · 2025-08-26T01:42:13Z

Thanks for your feedback, @dimas-b! I've updated the PR accordingly - please let me know if there is further feedback :)

adutra · 2025-08-26T16:02:04Z

runtime/service/src/main/java/org/apache/polaris/service/admin/EventsServiceDelegator.java

+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+// Used to annotate delegator classes, which are emitting events


Suggested change

// Used to annotate delegator classes, which are emitting events

/** Used to annotate delegator classes, which are emitting events. */

adutra · 2025-08-26T16:19:47Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+@EventsServiceDelegator
+@Alternative
+@Priority(1000) // Will allow downstream project-specific delegators to be added and used
+public class PolarisCatalogsServiceDefaultDelegator implements PolarisCatalogsApiService {


I like the general direction we are taking in this PR, but wanted to mention that this CDI pattern has dedicated annotations: @Decorator and @Delegate.

It's explained here:

https://quarkus.io/guides/cdi#decorators

https://jakarta.ee/specifications/cdi/3.0/jakarta-cdi-spec-3.0#decorator_bean

However, these annotations require both decorator and delegate beans to implement one common interface. This might not be possible for beans like IcebergCatalogAdapter since it's not an interface. We'd need to extract an interface from it in order to make the Decorator CDI pattern work.

Here, it could look like this:

@RequestScoped @Default @EventsServiceDelegator @Decorator @Priority(1000) // Will allow downstream project-specific delegators to be added and used public class PolarisCatalogsServiceDefaultDelegator implements PolarisCatalogsApiService { private final PolarisCatalogsApiService delegate; @Inject public PolarisCatalogsServiceDefaultDelegator(@Delegate @MainService PolarisCatalogsApiService delegate) { this.delegate = delegate; }

That said, I see that most adapters generally implement one or more interfaces, e.g.

@RequestScoped @MainService public class IcebergCatalogAdapter implements IcebergRestCatalogApiService, IcebergRestConfigurationApiService, CatalogAdapter {

So, maybe using @Decorator could work out of the box, if both beans (decorator and delegate) implement exactly the same interfaces (and there is no ambiguity when resolving beans).

This is a good suggestion, it helps make the code a bit tighter as well. Added in the next revision!

adutra · 2025-08-26T16:21:24Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+    this.delegate = delegate;
+  }
+
+  /** From PolarisCatalogsApiService */


nit: do we need these dummy javadocs?

These are copied from the original file, I didn't remove them. Happy to remove if you're more comfortable without them, but I originally didn't see any reason to remove these.

Hm what original file? I thought this file was new. This is a minor point though, so feel free to handle it as you see fit.

Sorry, I meant it came from PolarisServiceImpl.java, which was the base file that I was using for creating this file. Let me remove.

adutra · 2025-08-26T16:22:33Z

...main/java/org/apache/polaris/service/admin/PolarisPrincipalRolesServiceDefaultDelegator.java

+@EventsServiceDelegator
+@Alternative
+@Priority(1000) // Will allow downstream project-specific delegators to be added and used
+public class PolarisPrincipalRolesServiceDefaultDelegator


nit: the naming convention is a bit odd, I'd expect the decorator to be named <DelegateName>EventServiceDelegator or something like that.

hmm - I've tried naming everything into <DelegateName>DefaultDelegator rather than "...EventServiceDelegator" because in the following PRs, we will add the Events instrumentation to this Delegator. In other words, generating Events will be the default delegator. WDYT?

So... what happens if we need delegators for something else? E.g. PolarisDiagnostics could be turned into another delegator, e.g. <DelegateName>Diagnostics.

The beauty of @Decorator is that you can in theory have as many decorators you need, and each time the decorated interface is injected, CDI would transparently create a chain of invocations that traverse all the decorators up to the "undecorated" bean. IOW if you inject PolarisCatalogsApiService somewhere, calling PolarisCatalogsApiService.createCatalog() would actually call <DelegateName>Diagnostics.createCatalog() then <DelegateName>EventServiceDelegator.createCatalog() then PolarisServiceImpl.createCatalog().

I understand what you are saying now - I think I was originally closer to Dmitri's idea earlier in this PR by attempting to use a delegator wrapper without the Decorator pattern. Let me put a general comment on the PR regarding this and change the naming convention to more accurately reflect the Decorator pattern.

adutra · 2025-08-26T16:23:20Z

runtime/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceImpl.java


 /** Concrete implementation of the Polaris API services */
 @RequestScoped
+@MainService


This may not be necessary anymore when using proper interfaces and @Decorator / @Delegate.

You're correct - removed!

adutra

Thanks @adnanhemani for this proposal that seems to go into a clean direction.

adutra · 2025-08-26T16:30:32Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+@EventsServiceDelegator
+@Alternative
+@Priority(1000) // Will allow downstream project-specific delegators to be added and used
+public class PolarisCatalogsServiceDefaultDelegator implements PolarisCatalogsApiService {


That said, I see that most adapters generally implement one or more interfaces, e.g.

@RequestScoped @MainService public class IcebergCatalogAdapter implements IcebergRestCatalogApiService, IcebergRestConfigurationApiService, CatalogAdapter {

So, maybe using @Decorator could work out of the box, if both beans (decorator and delegate) implement exactly the same interfaces (and there is no ambiguity when resolving beans).

adnanhemani

Thanks @adutra for your feedback, I've push the revision addressing all the comments!

adnanhemani · 2025-08-26T21:59:20Z

runtime/service/src/main/java/org/apache/polaris/service/admin/EventsServiceDelegator.java

+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+// Used to annotate delegator classes, which are emitting events


adnanhemani · 2025-08-26T22:50:13Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+    this.delegate = delegate;
+  }
+
+  /** From PolarisCatalogsApiService */


These are copied from the original file, I didn't remove them. Happy to remove if you're more comfortable without them, but I originally didn't see any reason to remove these.

adnanhemani · 2025-08-26T22:57:23Z

...main/java/org/apache/polaris/service/admin/PolarisPrincipalRolesServiceDefaultDelegator.java

+@EventsServiceDelegator
+@Alternative
+@Priority(1000) // Will allow downstream project-specific delegators to be added and used
+public class PolarisPrincipalRolesServiceDefaultDelegator


hmm - I've tried naming everything into <DelegateName>DefaultDelegator rather than "...EventServiceDelegator" because in the following PRs, we will add the Events instrumentation to this Delegator. In other words, generating Events will be the default delegator. WDYT?

adnanhemani · 2025-08-27T01:03:57Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+@EventsServiceDelegator
+@Alternative
+@Priority(1000) // Will allow downstream project-specific delegators to be added and used
+public class PolarisCatalogsServiceDefaultDelegator implements PolarisCatalogsApiService {


This is a good suggestion, it helps make the code a bit tighter as well. Added in the next revision!

adnanhemani · 2025-08-27T01:04:18Z

runtime/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceImpl.java


 /** Concrete implementation of the Polaris API services */
 @RequestScoped
+@MainService


You're correct - removed!

adutra

LGTM thanks @adnanhemani – the naming convention is still imo a bit strange but we can change that later.

dimas-b

LGTM overall 👍

dimas-b · 2025-08-27T15:24:39Z

runtime/service/src/main/java/org/apache/polaris/service/admin/EventsServiceDelegator.java

+@Qualifier
+@Retention(RUNTIME)
+@Target({TYPE, METHOD, FIELD, PARAMETER})
+public @interface EventsServiceDelegator {}


maybe nitpicky, but "delegator" feels odd to me in a qualifier. A qualifier is supposed highlight a functional aspect of a bean, IMHO. Whether or not the bean delegates to other beans or genuinely implements and API should be be exposed in a qualifier, IMHO.

Would ServiceWithEvents or EventsEmitter (I assume it's supposed to emit events eventually) work?

dimas-b · 2025-08-27T15:36:34Z

I'm fine addressing naming concerns later if there's a general understanding that class and qualifier names will change :)

dimas-b · 2025-08-27T15:42:41Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+
+@EventsServiceDelegator
+@Default
+@Decorator


Using decorators is an interesting approach.

However, AFAIK, decorators are impossible to remove in downstream builds, right? I mean that if a decorator is discovered, it will be applied and all decorators will be applied in priority order. This means that all downstream users or runtime/service will always get this decorator in call paths.

This is fine, but I believe it might be wise to isolate the decorator in a new module (jar) to allow downstream projects to opt out of it.

That is correct. This situation is generally solved by either deactivating the decorator through some configuration flag, or, as you pointed out, by isolating the decorators in separated modules that integrators are free to include or exclude.

Good point. I suppose @IfBuildProperty(...) might be good enough for now (without introducing new modules).

... or perhaps @UnlessBuildProperty(...).

Agreed here with both of you. I'm leaning towards the @UnlessBuildProperty - but am thinking to leave this PR without it and let a future contribution make that change if anyone requires it.

That works for me 👍

Fair enough

dimas-b · 2025-08-27T15:43:58Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+import org.apache.polaris.core.context.RealmContext;
+import org.apache.polaris.service.admin.api.PolarisCatalogsApiService;
+
+@EventsServiceDelegator


The idea in my previous comment when I suggested using custom qualifiers was to use them for composing the delegation chain of *ApiService implementations.

However, if we go with the decorator approach, I believe this qualifier becomes rather useless 🤔 WDYT?

I asked myself the same question - but it all depends on how we are going to use these qualifiers, so I figured we would figure that out later 😅

I think you're right @dimas-b. Let me remove it for now and then if we think it'll be useful later, we can always reintroduce it in a new change!

adnanhemani

Thanks all for the feedback! There was a gradual shift from originally using a delegator wrapper to using the Decorator pattern in this PR - but I think we have reached convergence on this pattern based on the comments in this PR.

Naming conventions are still not finalized, but I believe this is the closest we have been so far to something usable as a base. I will be releasing further PRs using this as a base shortly for further event instrumentation.

adnanhemani · 2025-08-27T23:09:35Z

...main/java/org/apache/polaris/service/admin/PolarisPrincipalRolesServiceDefaultDelegator.java

+@EventsServiceDelegator
+@Alternative
+@Priority(1000) // Will allow downstream project-specific delegators to be added and used
+public class PolarisPrincipalRolesServiceDefaultDelegator


I understand what you are saying now - I think I was originally closer to Dmitri's idea earlier in this PR by attempting to use a delegator wrapper without the Decorator pattern. Let me put a general comment on the PR regarding this and change the naming convention to more accurately reflect the Decorator pattern.

adnanhemani · 2025-08-27T23:14:06Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+
+@EventsServiceDelegator
+@Default
+@Decorator


Agreed here with both of you. I'm leaning towards the @UnlessBuildProperty - but am thinking to leave this PR without it and let a future contribution make that change if anyone requires it.

adnanhemani · 2025-08-27T23:14:55Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+    this.delegate = delegate;
+  }
+
+  /** From PolarisCatalogsApiService */


Sorry, I meant it came from PolarisServiceImpl.java, which was the base file that I was using for creating this file. Let me remove.

adnanhemani · 2025-08-27T23:16:26Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsServiceDefaultDelegator.java

+import org.apache.polaris.core.context.RealmContext;
+import org.apache.polaris.service.admin.api.PolarisCatalogsApiService;
+
+@EventsServiceDelegator


I think you're right @dimas-b. Let me remove it for now and then if we think it'll be useful later, we can always reintroduce it in a new change!

adutra · 2025-08-28T07:21:56Z

...ice/src/main/java/org/apache/polaris/service/admin/PolarisCatalogsEventServiceDelegator.java

+
+@Decorator
+@Priority(1000)
+@Alternative


Hmm I think @Decorator is mutually exclusive with @Alternative.

Alternative beans provide a whole different bean implementation. Use it when you want to suppress the original bean's behavior. It's similar to mocking.

Decorators on the other hand are used to further specialize the original bean's behavior, without suppressing it. It's similar to AOP interceptors.

IMO what we are trying to achieve here is the second approach where the original bean keeps doing its job, but we add behavior before/after each invocation of the bean.

You are correct - I misread some documentation while looking up what would be required if we wanted to use @UnlessBuildProperty in the future and thought that @Alternative would be required at that time. Let me remove that property and push again!

RussellSpitzer · 2025-08-28T15:35:29Z

Looks good to me, I learned a lot about the delegator annotations allowed in the CDI from the discussion and it seems like this is a very straightforward pattern.

dimas-b · 2025-08-28T20:03:37Z

...e/src/main/java/org/apache/polaris/service/admin/PolarisPrincipalsEventServiceDelegator.java

+import org.apache.polaris.service.admin.api.PolarisPrincipalsApiService;
+
+@Decorator
+@Priority(1000)


nit: It might be worth adding a public constant for this priority value so that downstream projects could reference it... but it can be done later.

Fix undetected merge conflict after #2197 + #2415 + #2434 * Use local diagnostics in TransactionWorkspaceMetaStoreManager * Add resetCredentials to PolarisPrincipalsEventServiceDelegator

Add Delegator to all API Implementations

8f02a3a

github-project-automation bot added this to Basic Kanban Board Aug 22, 2025

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Aug 22, 2025

dimas-b reviewed Aug 22, 2025

View reviewed changes

...e/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceDefaultDelegator.java Outdated Show resolved Hide resolved

dimas-b reviewed Aug 22, 2025

View reviewed changes

adnanhemani added 2 commits August 23, 2025 00:57

Review comments from @dimas-b

f7f9cbc

Address feedback from @dimas-b

46a95ab

adnanhemani marked this pull request as ready for review August 26, 2025 01:41

singhpk234 previously approved these changes Aug 26, 2025

View reviewed changes

github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Aug 26, 2025

adutra reviewed Aug 26, 2025

View reviewed changes

Revision based on comments from @adutra

0bf0c79

adnanhemani dismissed singhpk234’s stale review via 0bf0c79 August 27, 2025 01:04

reverting accidental change

b64aa69

adnanhemani commented Aug 27, 2025

View reviewed changes

adutra previously approved these changes Aug 27, 2025

View reviewed changes

dimas-b reviewed Aug 27, 2025

View reviewed changes

eric-maynard previously approved these changes Aug 27, 2025

View reviewed changes

Changes based on reviews from @adutra and @dimas-b

05a9797

adnanhemani dismissed stale reviews from eric-maynard and adutra via 05a9797 August 27, 2025 23:28

adnanhemani commented Aug 27, 2025

View reviewed changes

singhpk234 previously approved these changes Aug 28, 2025

View reviewed changes

adutra reviewed Aug 28, 2025

View reviewed changes

Remove @Alternative annotation

ad46ca6

adnanhemani dismissed singhpk234’s stale review via ad46ca6 August 28, 2025 07:47

adutra approved these changes Aug 28, 2025

View reviewed changes

RussellSpitzer approved these changes Aug 28, 2025

View reviewed changes

dimas-b approved these changes Aug 28, 2025

View reviewed changes

eric-maynard merged commit b33c321 into apache:main Aug 28, 2025
12 checks passed

github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board Aug 28, 2025

dimas-b mentioned this pull request Sep 2, 2025

Fix CI #2489

Merged

dimas-b added a commit that referenced this pull request Sep 2, 2025

Fix CI (#2489)

f41d5bf

Fix undetected merge conflict after #2197 + #2415 + #2434 * Use local diagnostics in TransactionWorkspaceMetaStoreManager * Add resetCredentials to PolarisPrincipalsEventServiceDelegator

	// Used to annotate delegator classes, which are emitting events
	/** Used to annotate delegator classes, which are emitting events. */

Add Delegator to all API Implementations #2434

Add Delegator to all API Implementations #2434

Uh oh!

Conversation

adnanhemani commented Aug 22, 2025 • edited by singhpk234 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dimas-b Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adnanhemani Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adnanhemani commented Aug 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adnanhemani Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adutra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adnanhemani left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adnanhemani Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adutra left a comment

Choose a reason for hiding this comment

adnanhemani commented Aug 22, 2025 •

edited by singhpk234

Loading

dimas-b Aug 22, 2025 •

edited

Loading

adnanhemani Aug 23, 2025 •

edited

Loading

adnanhemani Aug 26, 2025 •

edited

Loading

adnanhemani Aug 26, 2025 •

edited

Loading

dimas-b Aug 27, 2025 •

edited

Loading

dimas-b Aug 27, 2025 •

edited

Loading

dimas-b Aug 27, 2025 •

edited

Loading