001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.client;
018
019import java.io.*;
020import java.net.http.*;
021
022/**
023 * Fluent builder for {@link JavaHttpTransport}.
024 *
025 * <p>
026 * Obtain an instance via {@link JavaHttpTransport#builder()}.
027 *
028 * <h2 class='section'>See Also:</h2><ul>
029 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/NextGenRestClient">Next-Generation REST Client</a>
030 * </ul>
031 *
032 * @since 9.2.1
033 */
034@SuppressWarnings({
035   "resource" // Not owned here; lifecycle is managed by the surrounding context
036})
037public final class JavaHttpTransportBuilder {
038
039   HttpClient httpClient;
040
041   long maxResponseBytes = JavaHttpTransport.DEFAULT_MAX_RESPONSE_BYTES;
042
043   boolean allowHostHeaderOverride;
044
045   JavaHttpTransportBuilder() {}
046
047   /**
048    * Opts in to sending a caller-controlled {@code Host} header, which pinning a policy-covered HTTP request needs.
049    *
050    * <p>
051    * The JDK {@link HttpClient} rejects a {@code Host} header unless the JVM property {@code jdk.httpclient.allowRestrictedHeaders}
052    * lists it.  Without this opt-in a policy-covered HTTP request that needs a {@code Host} override fails closed.
053    *
054    * <p>
055    * <b>This setting changes a JVM-wide property.</b>  Building the transport adds {@code host} to the system property
056    * {@code jdk.httpclient.allowRestrictedHeaders}, which affects every {@link HttpClient} in the JVM.  The JDK reads the
057    * property once, the first time any code builds a request header, so it only takes effect if that has not happened yet; otherwise
058    * start the JVM with {@code -Djdk.httpclient.allowRestrictedHeaders=host}.
059    *
060    * @return This object.
061    */
062   public JavaHttpTransportBuilder allowHostHeaderOverride() {
063      allowHostHeaderOverride = true;
064      return this;
065   }
066
067   /**
068    * Sets the maximum number of response body bytes the transport delivers; reading further fails with an {@link IOException}.
069    *
070    * @param value The cap in bytes.  Zero or negative means unlimited.  Defaults to {@link JavaHttpTransport#DEFAULT_MAX_RESPONSE_BYTES}.
071    * @return This object.
072    */
073   public JavaHttpTransportBuilder maxResponseBytes(long value) {
074      maxResponseBytes = value;
075      return this;
076   }
077
078   /**
079    * Sets the underlying {@link HttpClient} to use.
080    *
081    * <p>
082    * If not set, a default client is created via {@link HttpClient#newHttpClient()}.
083    *
084    * @param value The client to use. Can be <jk>null</jk> (a default client is created via {@link HttpClient#newHttpClient()}).
085    * @return This object.
086    */
087   public JavaHttpTransportBuilder httpClient(HttpClient value) {
088      httpClient = value;
089      return this;
090   }
091
092   /**
093    * Builds and returns the {@link JavaHttpTransport}.
094    *
095    * @return A new instance. Never <jk>null</jk>.
096    */
097   public JavaHttpTransport build() {
098      return new JavaHttpTransport(this);
099   }
100}