Add reference to ChainElement and the builder methods to place exec c…

…hain handler.
apache · Aug 31, 2023 · b94128d · b94128d
1 parent a7377f8
commit b94128d
Show file tree

Hide file tree

Showing 4 changed files with 26 additions and 0 deletions.
diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChainHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/async/AsyncExecChainHandler.java
@@ -28,7 +28,9 @@
 
 import java.io.IOException;
 
+import org.apache.hc.client5.http.impl.ChainElement;
 import org.apache.hc.client5.http.impl.async.AsyncHttpRequestRetryExec;
+import org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder;
 import org.apache.hc.core5.annotation.Contract;
 import org.apache.hc.core5.annotation.ThreadingBehavior;
 import org.apache.hc.core5.http.HttpException;
@@ -44,7 +46,16 @@
  * For information regarding the handler chain behaviour in case of a request re-execution,
  * please refer to the {@link AsyncHttpRequestRetryExec} javadoc.
  * </p>
+ * <p>
+ * Well known request execution handlers could be referred to by name using one of the
+ * {@link ChainElement} enum values.
+ * </p>
  * @since 5.0
+ * @see ChainElement
+ * @see HttpAsyncClientBuilder#addExecInterceptorFirst(String, AsyncExecChainHandler) 
+ * @see HttpAsyncClientBuilder#addExecInterceptorBefore(String, String, AsyncExecChainHandler)
+ * @see HttpAsyncClientBuilder#addExecInterceptorAfter(String, String, AsyncExecChainHandler)
+ * @see HttpAsyncClientBuilder#addExecInterceptorLast(String, AsyncExecChainHandler)
  */
 @Contract(threading = ThreadingBehavior.STATELESS)
 public interface AsyncExecChainHandler {

diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChainHandler.java b/httpclient5/src/main/java/org/apache/hc/client5/http/classic/ExecChainHandler.java
@@ -29,6 +29,8 @@
 
 import java.io.IOException;
 
+import org.apache.hc.client5.http.impl.ChainElement;
+import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
 import org.apache.hc.client5.http.impl.classic.HttpRequestRetryExec;
 import org.apache.hc.core5.annotation.Contract;
 import org.apache.hc.core5.annotation.ThreadingBehavior;
@@ -51,8 +53,17 @@
  * For information regarding the handler chain behaviour in case of a request re-execution,
  * please refer to the {@link HttpRequestRetryExec} javadoc.
  * </p>
+ *<p>
+ * Well known request execution handlers could be referred to by name using one of the
+ * {@link ChainElement} enum values.
+ *</p>
  *
  * @since 4.3
+ * @see ChainElement
+ * @see HttpClientBuilder#addExecInterceptorFirst(String, ExecChainHandler) 
+ * @see HttpClientBuilder#addExecInterceptorBefore(String, String, ExecChainHandler)
+ * @see HttpClientBuilder#addExecInterceptorAfter(String, String, ExecChainHandler) 
+ * @see HttpClientBuilder#addExecInterceptorLast(String, ExecChainHandler)
  */
 @Contract(threading = ThreadingBehavior.STATELESS)
 public interface ExecChainHandler {

diff --git a/...lient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncHttpRequestRetryExec.java b/...lient5/src/main/java/org/apache/hc/client5/http/impl/async/AsyncHttpRequestRetryExec.java
@@ -33,6 +33,7 @@
 import org.apache.hc.client5.http.async.AsyncExecCallback;
 import org.apache.hc.client5.http.async.AsyncExecChain;
 import org.apache.hc.client5.http.async.AsyncExecChainHandler;
+import org.apache.hc.client5.http.impl.ChainElement;
 import org.apache.hc.client5.http.protocol.HttpClientContext;
 import org.apache.hc.core5.annotation.Contract;
 import org.apache.hc.core5.annotation.Internal;
@@ -64,6 +65,7 @@
  * <p>
  * If this handler is active, pay particular attention to the placement
  * of other handlers within the handler chain relative to the retry handler.
+ * Use {@link ChainElement#RETRY} as name when referring to this handler.
  * </p>
  * <p>
  * If a custom handler is placed <b>before</b> the retry handler, the handler will

diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestRetryExec.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/classic/HttpRequestRetryExec.java
@@ -35,6 +35,7 @@
 import org.apache.hc.client5.http.classic.ExecChain.Scope;
 import org.apache.hc.client5.http.classic.ExecChainHandler;
 import org.apache.hc.client5.http.config.RequestConfig;
+import org.apache.hc.client5.http.impl.ChainElement;
 import org.apache.hc.client5.http.protocol.HttpClientContext;
 import org.apache.hc.core5.annotation.Contract;
 import org.apache.hc.core5.annotation.Internal;
@@ -64,6 +65,7 @@
  * <p>
  * If this handler is active, pay particular attention to the placement
  * of other handlers within the handler chain relative to the retry handler.
+ * Use {@link ChainElement#RETRY} as name when referring to this handler.
  * </p>
  * <p>
  * If a custom handler is placed <b>before</b> the retry handler, the handler will