Document a Workaround for HTTP Patch & provide tests

Signed-off-by: jansupol <jan.supol@oracle.com>

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

@@ -94,7 +94,7 @@ public class HttpUrlConnectorProvider implements ConnectorProvider {
  /**
  * A value of {@code true} declares that the client will try to set
  * unsupported HTTP method to {@link java.net.HttpURLConnection} via
- * reflection.
+ * reflection as a workaround for a missing HTTP method.
  * <p>
  * NOTE: Enabling this property may cause security related warnings/errors
  * and it may break when other JDK implementation is used. <b>Use only
@@ -103,6 +103,10 @@ public class HttpUrlConnectorProvider implements ConnectorProvider {
  * <p>The value MUST be an instance of {@link java.lang.Boolean}.</p>
  * <p>The default value is {@code false}.</p>
  * <p>The name of the configuration property is <tt>{@value}</tt>.</p>
+ * <p>Since JDK 16 the JDK internal classes are not opened for reflection and the workaround method does not work,
+ * unless {@code --add-opens java.base/java.net=ALL-UNNAMED} for HTTP requests and additional
+ * {@code --add-opens java.base/sun.net.www.protocol.https=ALL-UNNAMED} for HTTPS (HttpsUrlConnection) options are set.
+ * </p>
  */
  public static final String SET_METHOD_WORKAROUND =
  "jersey.config.client.httpUrlConnection.setMethodWorkaround";

docs/src/main/docbook/appendix-properties.xml

@@ -1301,6 +1301,88 @@
  </table>
 
 
+ </section>
+ <section xml:id="appendix-properties-client-default">
+ <title>The default HttpUrlConnector properties</title>
+ <para>
+ List of properties defined in &jersey.client.HttpUrlConnectorProvider; class.
+ </para>
+
+ <table>
+ <title>List of the default &jersey.client.HttpUrlConnectorProvider; properites</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Constant</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>&jersey.client.HttpUrlConnectorProvider.SET_METHOD_WORKAROUND;</entry>
+ <entry><literal>jersey.config.client.httpUrlConnection.setMethodWorkaround</literal></entry>
+ <entry>
+ <para>
+ A value of &lit.true; declares that the client will try to set
+ unsupported HTTP method to <literal>java.net.HttpURLConnection</literal> via
+ reflection as a workaround for a missing HTTP method.
+ </para>
+ <para>
+ NOTE: Enabling this property may cause security related warnings/errors
+ and it may break when other JDK implementation is used. <emphasis>Use only
+ when you know what you are doing.</emphasis>
+ </para>
+ <para>
+ The value MUST be an instance of &lit.jdk6.Boolean;. The default value is &lit.false;.
+ </para>
+ <para>Since JDK 16 the JDK internal classes are not opened for reflection and the workaround method
+ does not work, unless <literal>--add-opens java.base/java.net=ALL-UNNAMED</literal> for HTTP
+ requests and additional <literal>--add-opens java.base/sun.net.www.protocol.https=ALL-UNNAMED</literal>
+ for HTTPS (<literal>javax.net.ssl.HttpsUrlConnection</literal>) options are set.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>&jersey.client.HttpUrlConnectorProvider.USE_FIXED_LENGTH_STREAMING;</entry>
+ <entry><literal>jersey.config.client.httpUrlConnector.useFixedLengthStreaming</literal></entry>
+ <entry>
+ <para>
+ If &lit.true;, the &lit.jersey.client.HttpUrlConnector; (if used) will assume the content length
+ from the value of <literal>javax.ws.rs.core.HttpHeaders#CONTENT_LENGTH</literal> request
+ header (if present).
+ </para>
+ <para>
+ When this property is enabled and the request has a valid non-zero content length
+ value specified in its <literal>javax.ws.rs.core.HttpHeaders#CONTENT_LENGTH</literal> request
+ header, that this value will be used as an input to the
+ <literal>java.net.HttpURLConnection#setFixedLengthStreamingMode(int)</literal> method call
+ invoked on the underlying <literal>java.net.HttpURLConnection</literal>.
+ This will also suppress the entity buffering in the <literal>HttpURLConnection</literal>,
+ which is undesirable in certain scenarios, e.g. when streaming large entities.
+ </para>
+ <para>
+ Note that the content length value defined in the request header must exactly match
+ the real size of the entity. If the <literal>javax.ws.rs.core.HttpHeaders#CONTENT_LENGTH</literal>
+ header is explicitly specified in a request, this property will be ignored and the
+ request entity will be still buffered by the underlying <literal>HttpURLConnection</literal> infrastructure.
+ </para>
+ <para>
+ This property also overrides the behaviour enabled by the &jersey.client.ClientProperties.CHUNKED_ENCODING_SIZE;
+ property. Chunked encoding will only be used, if the size is not specified in the header of the request.
+ </para>
+ <para>
+ Note that this property only applies to client run-times that are configured to use the default
+ &lit.jersey.client.HttpUrlConnector; as the client connector. The property is ignored by other connectors.
+ </para>
+ <para>
+ The default value is &lit.false;.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
  </section>
  <section xml:id="appendix-properties-client-apache">
  <title>Apache HTTP client configuration properties</title>