Adjust getRequestHeader method (#4893)

* Adjust getRequestHeader method (3.1 spec)

Signed-off-by: Maxim Nesen <[email protected]>

Author: senivam

core-client/src/main/java/org/glassfish/jersey/client/ClientRequest.java

@@ -229,9 +229,19 @@ ClientConfig getClientConfig() {
         return clientConfig;
     }
 
+    /**
+     * Get the values of an HTTP request header if the header exists on the current request. The returned value will be
+     * a read-only List if the specified header exists or {@code null} if it does not. This is a shortcut for
+     * {@code getRequestHeaders().get(name)}.
+     *
+     * @param name the header name, case insensitive.
+     * @return a read-only list of header values if the specified header exists, otherwise {@code null}.
+     * @throws java.lang.IllegalStateException if called outside the scope of a request.
+     */
     @Override
     public List<String> getRequestHeader(String name) {
-        return HeaderUtils.asStringList(getHeaders().get(name), clientConfig.getConfiguration());
+        final List<Object> values = getHeaders().get(name);
+        return values == null ? null : HeaderUtils.asStringList(values, clientConfig.getConfiguration());
     }
 
     @Override

core-server/src/main/java/org/glassfish/jersey/server/ContainerRequest.java

@@ -821,13 +821,13 @@ private static long roundDown(final long time) {
     }
 
     /**
-     * Get the values of a HTTP request header. The returned List is read-only.
-     * This is a shortcut for {@code getRequestHeaders().get(name)}.
+     * Get the values of an HTTP request header if the header exists on the current request. The returned value will be
+     * a read-only List if the specified header exists or {@code null} if it does not. This is a shortcut for
+     * {@code getRequestHeaders().get(name)}.
      *
      * @param name the header name, case insensitive.
-     * @return a read-only list of header values.
-     *
-     * @throws IllegalStateException if called outside the scope of a request.
+     * @return a read-only list of header values if the specified header exists, otherwise {@code null}.
+     * @throws java.lang.IllegalStateException if called outside the scope of a request.
      */
     @Override
     public List<String> getRequestHeader(final String name) {

docs/src/main/docbook/jaxrs-resources.xml

@@ -480,6 +480,11 @@ public String get(@Context HttpHeaders hh) {
             </example>
         </para>
 
+        <para>
+            For quicker getting of values for a known header name there is a shortcut for <literal>hh.getRequestHeaders().get(name)</literal>
+            which is <literal>hh.getRequestHeader(name)</literal>.
+        </para>
+
         <para>In general &jaxrs.core.Context; can be used to obtain contextual Java types related to the request or response.
         </para>
 

docs/src/main/docbook/migration.xml

@@ -100,6 +100,13 @@
                             <literal>true</literal>.
                         </para>
                     </listitem>
+                    <listitem>
+                        <para>
+                            Since Jersey 3.1.0+ the <literal>getRequestHeader(String name)</literal> method of the
+                            <literal>ClientRequest</literal> class returns NULL (instead of an empty List) in case if
+                            the specified header does not exist.
+                        </para>
+                    </listitem>
                 </itemizedlist>
             </para>
         </section>