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.okhttp;
018
019
020import java.net.*;
021
022import okhttp3.*;
023import static org.apache.juneau.commons.utils.Shorts.*;
024
025/**
026 * Fluent builder for {@link OkHttpTransport}.
027 *
028 * <p>
029 * Obtain an instance via {@link OkHttpTransport#builder()}.
030 *
031 * <h5 class='section'>See Also:</h5><ul>
032 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/NextGenRestClient">Next-Generation REST Client</a>
033 * </ul>
034 *
035 * @since 9.2.1
036 */
037@SuppressWarnings({
038   "resource" // Builder methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
039})
040public final class OkHttpTransportBuilder {
041
042   OkHttpClient httpClient;
043
044   OkHttpTransportBuilder() {}
045
046   /**
047    * Sets the underlying {@link OkHttpClient} to use.
048    *
049    * <p>
050    * If not set, a default client is created via {@code new OkHttpClient()}.
051    *
052    * <p>
053    * A client with an explicit {@linkplain OkHttpClient#proxy() proxy} makes {@link OkHttpTransport#supportsUrlPolicy()}
054    * report <jk>false</jk> (the proxy resolves the target host itself, bypassing the SSRF guard's address pinning), so
055    * {@code RestRequest} refuses to send an SSRF-guard-active request through it.  A client whose
056    * {@link ProxySelector} routes a guarded request through a proxy is refused at send time.
057    *
058    * <p>
059    * The transport sends through a client derived from this one with {@link OkHttpClient#newBuilder()} (it shares the
060    * connection pool, dispatcher and settings), adding a network interceptor that strips caller-set credential headers
061    * ({@code Authorization}, {@code Cookie} and the rest of {@link org.apache.juneau.rest.client.RedirectSecurity#stripOnCrossOrigin()})
062    * when OkHttp follows a redirect to a different origin.  The client passed in is not modified.
063    *
064    * <p>
065    * Once a hop has been stripped, later hops of the same call stay stripped, including one back to the first origin.  That
066    * state travels on a tag of the request, so a network interceptor or an {@link okhttp3.Authenticator} on the client
067    * that builds a request from scratch (rather than from {@code request.newBuilder()}) must preserve the request's tags,
068    * or the sticky strip is lost.
069    *
070    * <p>
071    * OkHttp recommends sharing a single {@link OkHttpClient} instance across the application.
072    * When sharing, the caller is responsible for lifecycle management; {@link OkHttpTransport#close()}
073    * will still attempt to drain the client's connection pool and executor.
074    *
075    * @param value The client to use. Must not be <jk>null</jk>.
076    * @return This object.
077    */
078   public OkHttpTransportBuilder httpClient(OkHttpClient value) {
079      httpClient = reqnn("value", value);
080      return this;
081   }
082
083   /**
084    * Builds and returns the {@link OkHttpTransport}.
085    *
086    * @return A new instance. Never <jk>null</jk>.
087    */
088   public OkHttpTransport build() {
089      return new OkHttpTransport(this);
090   }
091}