From 5e99e8add979eaf2282b749c11b4c7d3f367c532 Mon Sep 17 00:00:00 2001 From: Michael Marshall Date: Fri, 20 Jan 2023 01:35:40 -0600 Subject: [PATCH] [improve][broker] Documentation for AuthenticationState contract (#19283) (cherry picked from commit de3b85545a72ecd83081530a9d0980ef1d6660da) --- .../authentication/AuthenticationState.java | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationState.java b/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationState.java index 0e5dcc3121f27..89b3ee2777e90 100644 --- a/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationState.java +++ b/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationState.java @@ -19,16 +19,25 @@ package org.apache.pulsar.broker.authentication; +import java.net.SocketAddress; import java.util.concurrent.CompletableFuture; import javax.naming.AuthenticationException; +import javax.net.ssl.SSLSession; import org.apache.pulsar.common.api.AuthData; import org.apache.pulsar.common.util.FutureUtil; /** * Interface for authentication state. - * - * It tell broker whether the authentication is completed or not, - * if completed, what is the AuthRole is. + *

+ * Pulsar integrates with this class in the following order: + * 1. Initialize the class by calling {@link AuthenticationProvider#newAuthState(AuthData, SocketAddress, SSLSession)} + * 2. Call {@link #authenticate(AuthData)}. If result is not null, send to client. And call + * {@link #authenticate(AuthData)} with the client's response. Repeat until result of {@link #authenticate(AuthData)} + * is null or an exception. + * 3. Call {@link #getAuthRole()} and {@link #getAuthDataSource()} to use for authentication. It is expected that these + * responses update with each call to {@link #authenticate(AuthData)}. + * 4. Poll {@link #isExpired()} until it returns true. + * 5. Call {@link #refreshAuthentication()} and GoTo step 2 when client responds. */ public interface AuthenticationState { /**