Add mode documentation on QUERY usage

apache · Oct 19, 2024 · 731e683 · 731e683
1 parent 40d9d26
commit 731e683
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 0 deletions.
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/Method.java b/httpcore5/src/main/java/org/apache/hc/core5/http/Method.java
@@ -95,6 +95,11 @@ public enum Method {
 
     /**
      * The HTTP {@code QUERY} method is safe and idempotent.
+     * <p>
+     * {@code QUERY} is a method defined to represent a safe, idempotent request that carries a body.
+     * This allows clients to send a body while enjoying the {@code GET}-like properties (such as easy caching,
+     * safe CORS handling [if supported] and bookmarking), as well as the {@code POST}-like properties (such as
+     * being able to send a query in a richer format, and not being limited by URI length and escaping restrictions).
      *
      * @since 5.4
      */

diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/ClassicRequestBuilder.java b/httpcore5/src/main/java/org/apache/hc/core5/http/io/support/ClassicRequestBuilder.java
@@ -121,20 +121,34 @@ public static ClassicRequestBuilder head(final String uri) {
     }
 
     /**
+     * Initializes a new {@link ClassicRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static ClassicRequestBuilder query() {
         return new ClassicRequestBuilder(Method.QUERY);
     }
 
     /**
+     * Initializes a new {@link ClassicRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @param uri the request URI.
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static ClassicRequestBuilder query(final URI uri) {
         return new ClassicRequestBuilder(Method.QUERY, uri);
     }
 
     /**
+     * Initializes a new {@link ClassicRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @param uri the request URI.
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static ClassicRequestBuilder query(final String uri) {

diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncRequestBuilder.java b/httpcore5/src/main/java/org/apache/hc/core5/http/nio/support/AsyncRequestBuilder.java
@@ -121,20 +121,34 @@ public static AsyncRequestBuilder head(final String uri) {
     }
 
     /**
+     * Initializes a new {@link AsyncRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static AsyncRequestBuilder query() {
         return new AsyncRequestBuilder(Method.QUERY);
     }
 
     /**
+     * Initializes a new {@link AsyncRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @param uri the request URI.
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static AsyncRequestBuilder query(final URI uri) {
         return new AsyncRequestBuilder(Method.QUERY, uri);
     }
 
     /**
+     * Initializes a new {@link AsyncRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @param uri the request URI.
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static AsyncRequestBuilder query(final String uri) {

diff --git a/httpcore5/src/main/java/org/apache/hc/core5/http/support/BasicRequestBuilder.java b/httpcore5/src/main/java/org/apache/hc/core5/http/support/BasicRequestBuilder.java
@@ -105,20 +105,34 @@ public static BasicRequestBuilder head(final String uri) {
     }
 
     /**
+     * Initializes a new {@link BasicRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static BasicRequestBuilder query() {
         return new BasicRequestBuilder(Method.QUERY);
     }
 
     /**
+     * Initializes a new {@link BasicRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @param uri the request URI.
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static BasicRequestBuilder query(final URI uri) {
         return new BasicRequestBuilder(Method.QUERY, uri);
     }
 
     /**
+     * Initializes a new {@link BasicRequestBuilder} instance for the {@code QUERY} method.
+     *
+     * @param uri the request URI.
+     * @see Method#QUERY for more information regarding the properties of the {@code QUERY} method.
+     *
      * @since 5.4
      */
     public static BasicRequestBuilder query(final String uri) {