From a51222f502cb42e583f42b716fcea0d89d77b7b6 Mon Sep 17 00:00:00 2001
From: Thomas Segismont <tsegismo@ibm.com>
Date: Mon, 24 Nov 2025 12:08:44 +0100
Subject: [PATCH] Improve Javadoc for CredentialsProvider

See https://github.com/quarkusio/quarkus/pull/50047#issuecomment-3570026112

The goal is to provide guidance to implementors on whether to implement the synchronous or the asynchronous variant.
---
 .../io/quarkus/credentials/CredentialsProvider.java   | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/extensions/credentials/runtime/src/main/java/io/quarkus/credentials/CredentialsProvider.java b/extensions/credentials/runtime/src/main/java/io/quarkus/credentials/CredentialsProvider.java
index 0dea4a46e5246..fc9a7ab18f3fe 100644
--- a/extensions/credentials/runtime/src/main/java/io/quarkus/credentials/CredentialsProvider.java
+++ b/extensions/credentials/runtime/src/main/java/io/quarkus/credentials/CredentialsProvider.java
@@ -12,6 +12,17 @@
  * <p>
  * The default implementation of asynchronous variant invokes the synchronous {@link #getCredentials(String)} on a worker
  * thread.
+ * <p>
+ * Note that there is a price to pay for offloading a task to a worker thread.
+ * Nevertheless, if the implementation of the synchronous {@link #getCredentials(String)} involves blocking APIs, it is the
+ * right thing to do.
+ * Otherwise, it could block an event-loop thread, which
+ * <a href="https://quarkus.io/guides/duplicated-context#the-reactive-model"><strong>MUST</strong> be avoided</a>.
+ * <p>
+ * When the implementation does not invoke blocking APIs, prefer overriding the asynchronous
+ * {@link #getCredentialsAsync(String)}, instead of the synchronous variant.
+ * For example, if a provider caches credentials in memory and refreshes them in the background, it is not necessary to switch
+ * to a worker thread to read them.
  */
 public interface CredentialsProvider {