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.apachehttpclient50;
018
019
020import org.apache.hc.client5.http.impl.classic.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022
023/**
024 * Fluent builder for {@link ApacheHc5Transport}.
025 *
026 * <p>
027 * Obtain an instance via {@link ApacheHc5Transport#builder()}.
028 *
029 * <h5 class='section'>See Also:</h5><ul>
030 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/NextGenRestClient">Next-Generation REST Client</a>
031 * </ul>
032 *
033 * @since 9.2.1
034 */
035@SuppressWarnings({
036   "resource" // Builder methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
037})
038public final class ApacheHc5TransportBuilder {
039
040   CloseableHttpClient httpClient;
041
042   ApacheHc5TransportBuilder() {}
043
044   /**
045    * Sets the underlying {@link CloseableHttpClient} to use.
046    *
047    * <p>
048    * If not set, the transport creates its own default clients: one for ordinary requests, and one with a separate
049    * connection pool whose connections are all pinned to a policy-allowed address, for SSRF-guard-active
050    * {@code @Remote} requests.
051    *
052    * <p>
053    * A caller-supplied client cannot be given that pin-on-connect pool, so a transport built with one reports
054    * {@link ApacheHc5Transport#supportsUrlPolicy()} as <jk>false</jk>, and {@code RestRequest} refuses to send an
055    * SSRF-guard-active request through it.
056    *
057    * <p>
058    * The transport takes ownership of the client and will close it when {@link ApacheHc5Transport#close()} is called.
059    *
060    * @param value The client to use. Must not be <jk>null</jk>.
061    * @return This object.
062    */
063   public ApacheHc5TransportBuilder httpClient(CloseableHttpClient value) {
064      httpClient = reqnn("value", value);
065      return this;
066   }
067
068   /**
069    * Builds and returns the {@link ApacheHc5Transport}.
070    *
071    * @return A new instance. Never <jk>null</jk>.
072    */
073   public ApacheHc5Transport build() {
074      return new ApacheHc5Transport(this);
075   }
076}