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.apachehttpclient45;
018
019
020import org.apache.http.impl.client.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022
023/**
024 * Fluent builder for {@link ApacheHc45Transport}.
025 *
026 * <p>
027 * Obtain an instance via {@link ApacheHc45Transport#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 ApacheHc45TransportBuilder {
039
040   CloseableHttpClient httpClient;
041
042   ApacheHc45TransportBuilder() {}
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 ApacheHc45Transport#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 ApacheHc45Transport#close()} is called.
059    *
060    * <p>
061    * A legacy {@link AbstractHttpClient} subclass (such as {@code DefaultHttpClient}) is refused: it never sets the request
062    * again just before it is written, so the redirect credential guard cannot strip the credentials HttpClient adds itself
063    * (for example the cookie-store {@code Cookie}) on a cross-origin redirect.  Build the client with {@code HttpClients}.
064    *
065    * @param value The client to use. Must not be <jk>null</jk>.
066    * @return This object.
067    * @throws IllegalArgumentException If the client is an {@link AbstractHttpClient}.
068    */
069   @SuppressWarnings({
070      "deprecation" // AbstractHttpClient is referenced only to refuse the legacy client type; there is no replacement check.
071   })
072   public ApacheHc45TransportBuilder httpClient(CloseableHttpClient value) {
073      if (reqnn("value", value) instanceof AbstractHttpClient)
074         throw iaex("A legacy AbstractHttpClient (%s) is not supported: it cannot apply the redirect credential guard.  Build the client with HttpClients instead.", value.getClass().getName());
075      httpClient = value;
076      return this;
077   }
078
079   /**
080    * Builds and returns the {@link ApacheHc45Transport}.
081    *
082    * @return A new instance. Never <jk>null</jk>.
083    */
084   public ApacheHc45Transport build() {
085      return new ApacheHc45Transport(this);
086   }
087}