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.jetty;
018
019
020import org.eclipse.jetty.client.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022
023/**
024 * Fluent builder for {@link JettyHttpTransport}.
025 *
026 * <p>
027 * Obtain an instance via {@link JettyHttpTransport#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 JettyHttpTransportBuilder {
039
040   HttpClient httpClient;
041   long responseTimeoutMs = 30_000;
042
043   JettyHttpTransportBuilder() {}
044
045   /**
046    * Sets the underlying {@link HttpClient} to use.
047    *
048    * <p>
049    * If not set, a default client is created via {@code new HttpClient()}.
050    *
051    * <p>
052    * If the provided client has not been started, {@link JettyHttpTransport} will start it automatically.
053    * When {@link JettyHttpTransport#close()} is called, the client will be stopped.
054    *
055    * <p>
056    * The client itself is not changed.  So that a redirect it follows does not carry caller-set credential headers to
057    * another origin, the transport creates each request itself, as a guarded subclass of Jetty's request, instead of
058    * calling {@link HttpClient#newRequest(java.net.URI)}; an override of that method is not called.  Customize requests
059    * with the client's own settings and request listeners instead.
060    *
061    * @param value The client to use. Must not be <jk>null</jk>.
062    * @return This object.
063    */
064   public JettyHttpTransportBuilder httpClient(HttpClient value) {
065      httpClient = reqnn("value", value);
066      return this;
067   }
068
069   /**
070    * Sets the maximum time to wait for the response headers to arrive after the request is sent.
071    *
072    * <p>
073    * This timeout covers the time from when the request is fully sent until the first response line and headers
074    * are received.  It does not limit how long the response body may take to stream.
075    * Defaults to {@code 30_000} ms (30 seconds).
076    *
077    * @param value The timeout in milliseconds. Use {@code 0} or a negative value to wait indefinitely.
078    * @return This object.
079    */
080   public JettyHttpTransportBuilder responseTimeoutMs(long value) {
081      responseTimeoutMs = value;
082      return this;
083   }
084
085   /**
086    * Builds and returns the {@link JettyHttpTransport}.
087    *
088    * @return A new instance. Never <jk>null</jk>.
089    * @throws Exception If the Jetty {@link HttpClient} cannot be started.
090    */
091   public JettyHttpTransport build() throws Exception {
092      return new JettyHttpTransport(this);
093   }
094}