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}