https://github.com/eclipse-ee4j/jaxrs-api: Jakarta RESTful Web Services (Eclipse Foundation) 
/*
 * Copyright (c) 2011, 2019 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.ws.rs.client;

import java.net.URL;
import java.security.KeyStore;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.SSLContext;

import jakarta.ws.rs.ProcessingException;
import jakarta.ws.rs.core.Configurable;
import jakarta.ws.rs.core.Configuration;
import jakarta.ws.rs.sse.SseEventSource;


Main entry point to the client API used to bootstrap Client instances. 
Author:Marek Potociar
Since:2.0
/**
 * Main entry point to the client API used to bootstrap {@link jakarta.ws.rs.client.Client} instances.
 *
 * @author Marek Potociar
 * @since 2.0
 */
public abstract class ClientBuilder implements Configurable<ClientBuilder> {

    
Name of the property identifying the ClientBuilder implementation to be returned from newBuilder(). 
/**
     * Name of the property identifying the {@link ClientBuilder} implementation to be returned from
     * {@link ClientBuilder#newBuilder()}.
     */
    public static final String JAXRS_DEFAULT_CLIENT_BUILDER_PROPERTY = "jakarta.ws.rs.client.ClientBuilder";

    
Allows custom implementations to extend the ClientBuilder class. 
/**
     * Allows custom implementations to extend the {@code ClientBuilder} class.
     */
    protected ClientBuilder() {
    }

    
Create a new ClientBuilder instance using the default client builder implementation class provided by the JAX-RS implementation provider. 
Returns:new client builder instance.
/**
     * Create a new {@code ClientBuilder} instance using the default client builder implementation class provided by the
     * JAX-RS implementation provider.
     *
     * @return new client builder instance.
     */
    public static ClientBuilder newBuilder() {
        try {
            Object delegate = FactoryFinder.find(JAXRS_DEFAULT_CLIENT_BUILDER_PROPERTY, ClientBuilder.class);
            if (!(delegate instanceof ClientBuilder)) {
                Class pClass = ClientBuilder.class;
                String classnameAsResource = pClass.getName().replace('.', '/') + ".class";
                ClassLoader loader = pClass.getClassLoader();
                if (loader == null) {
                    loader = ClassLoader.getSystemClassLoader();
                }
                URL targetTypeURL = loader.getResource(classnameAsResource);
                throw new LinkageError("ClassCastException: attempting to cast"
                        + delegate.getClass().getClassLoader().getResource(classnameAsResource)
                        + " to " + targetTypeURL);
            }
            return (ClientBuilder) delegate;
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }

    
Create a new Client instance using the default client builder implementation class provided by the JAX-RS implementation provider. 
Returns:new client instance.
/**
     * Create a new {@link Client} instance using the default client builder implementation class provided by the JAX-RS
     * implementation provider.
     *
     * @return new client instance.
     */
    public static Client newClient() {
        return newBuilder().build();
    }

    
Create a new custom-configured Client instance using the default client builder implementation class provided by the JAX-RS implementation provider. 
Params:
  • configuration – data used to provide initial configuration for the new client instance.
Returns:new configured client instance.
/**
     * Create a new custom-configured {@link Client} instance using the default client builder implementation class provided
     * by the JAX-RS implementation provider.
     *
     * @param configuration data used to provide initial configuration for the new client instance.
     * @return new configured client instance.
     */
    public static Client newClient(final Configuration configuration) {
        return newBuilder().withConfig(configuration).build();
    }

    
Set the internal configuration state to an externally provided configuration state.

Params:
  • config – external configuration state to replace the configuration of this configurable instance.
Returns:the updated client builder instance.
/**
     * Set the internal configuration state to an externally provided configuration state.
     *
     * @param config external configuration state to replace the configuration of this configurable instance.
     * @return the updated client builder instance.
     */
    public abstract ClientBuilder withConfig(Configuration config);

    
Set the SSL context that will be used when creating secured transport connections to server endpoints from web targets created by the client instance that is using this SSL context. The SSL context is expected to have all the security infrastructure initialized, including the key and trust managers. 
 Setting a SSL context instance resets any key store or trust store values previously specified. 


Params:
  • sslContext – secure socket protocol implementation which acts as a factory for secure socket factories or SSL engines. Must not be null.
Throws:
See Also:
Returns:an updated client builder instance.
/**
     * Set the SSL context that will be used when creating secured transport connections to server endpoints from
     * {@link WebTarget web targets} created by the client instance that is using this SSL context. The SSL context is
     * expected to have all the security infrastructure initialized, including the key and trust managers.
     * <p>
     * Setting a SSL context instance resets any {@link #keyStore(java.security.KeyStore, char[]) key store} or
     * {@link #trustStore(java.security.KeyStore) trust store} values previously specified.
     * </p>
     *
     * @param sslContext secure socket protocol implementation which acts as a factory for secure socket factories or
     * {@link javax.net.ssl.SSLEngine SSL engines}. Must not be {@code null}.
     * @return an updated client builder instance.
     * @throws NullPointerException in case the {@code sslContext} parameter is {@code null}.
     * @see #keyStore(java.security.KeyStore, char[])
     * @see #keyStore(java.security.KeyStore, String)
     * @see #trustStore
     */
    public abstract ClientBuilder sslContext(final SSLContext sslContext);

    
Set the client-side key store. Key store contains client's private keys, and the certificates with their
corresponding public keys.

 Setting a key store instance resets any SSL context instance value previously specified. 



Note that a custom key store is only required if you want to enable a custom setup of a 2-way SSL connections (client
certificate authentication).



Params:
  • keyStore – client-side key store. Must not be null.
  • password – client key password. Must not be null.
Throws:
See Also:
Returns:an updated client builder instance.
/**
     * Set the client-side key store. Key store contains client's private keys, and the certificates with their
     * corresponding public keys.
     * <p>
     * Setting a key store instance resets any {@link #sslContext(javax.net.ssl.SSLContext) SSL context instance} value
     * previously specified.
     * </p>
     * <p>
     * Note that a custom key store is only required if you want to enable a custom setup of a 2-way SSL connections (client
     * certificate authentication).
     * </p>
     *
     * @param keyStore client-side key store. Must not be {@code null}.
     * @param password client key password. Must not be {@code null}.
     * @return an updated client builder instance.
     * @throws NullPointerException in case any of the supplied parameters is {@code null}.
     * @see #sslContext
     * @see #keyStore(java.security.KeyStore, String)
     * @see #trustStore
     */
    public abstract ClientBuilder keyStore(final KeyStore keyStore, final char[] password);

    
Set the client-side key store. Key store contains client's private keys, and the certificates with their
corresponding public keys.

 Setting a key store instance resets any SSL context instance value previously specified. 


 Note that for improved security of working with password data and avoid storing passwords in Java string objects, the keyStore(KeyStore, char[]) version of the method can be utilized. Also note that a custom key store is only required if you want to enable a custom setup of a 2-way SSL connections (client certificate authentication). 


Params:
  • keyStore – client-side key store. Must not be null.
  • password – client key password. Must not be null.
Throws:
See Also:
Returns:an updated client builder instance.
/**
     * Set the client-side key store. Key store contains client's private keys, and the certificates with their
     * corresponding public keys.
     * <p>
     * Setting a key store instance resets any {@link #sslContext(javax.net.ssl.SSLContext) SSL context instance} value
     * previously specified.
     * </p>
     * <p>
     * Note that for improved security of working with password data and avoid storing passwords in Java string objects, the
     * {@link #keyStore(java.security.KeyStore, char[])} version of the method can be utilized. Also note that a custom key
     * store is only required if you want to enable a custom setup of a 2-way SSL connections (client certificate
     * authentication).
     * </p>
     *
     * @param keyStore client-side key store. Must not be {@code null}.
     * @param password client key password. Must not be {@code null}.
     * @return an updated client builder instance.
     * @throws NullPointerException in case any of the supplied parameters is {@code null}.
     * @see #sslContext
     * @see #keyStore(java.security.KeyStore, char[])
     * @see #trustStore
     */
    public ClientBuilder keyStore(final KeyStore keyStore, final String password) {
        return keyStore(keyStore, password.toCharArray());
    }

    
Set the client-side trust store. Trust store is expected to contain certificates from other parties the client is you
expect to communicate with, or from Certificate Authorities that are trusted to identify other parties.

 Setting a trust store instance resets any SSL context instance value previously specified. 



In case a custom trust store or custom SSL context is not specified, the trust management will be configured to use
the default Java runtime settings.



Params:
  • trustStore – client-side trust store. Must not be null.
Throws:
See Also:
Returns:an updated client builder instance.
/**
     * Set the client-side trust store. Trust store is expected to contain certificates from other parties the client is you
     * expect to communicate with, or from Certificate Authorities that are trusted to identify other parties.
     * <p>
     * Setting a trust store instance resets any {@link #sslContext(javax.net.ssl.SSLContext) SSL context instance} value
     * previously specified.
     * </p>
     * <p>
     * In case a custom trust store or custom SSL context is not specified, the trust management will be configured to use
     * the default Java runtime settings.
     * </p>
     *
     * @param trustStore client-side trust store. Must not be {@code null}.
     * @return an updated client builder instance.
     * @throws NullPointerException in case the supplied trust store parameter is {@code null}.
     * @see #sslContext
     * @see #keyStore(java.security.KeyStore, char[])
     * @see #keyStore(java.security.KeyStore, String)
     */
    public abstract ClientBuilder trustStore(final KeyStore trustStore);

    
Set the hostname verifier to be used by the client to verify the endpoint's hostname against it's identification
information.

Params:
  • verifier – hostname verifier.
Returns:an updated client builder instance.
/**
     * Set the hostname verifier to be used by the client to verify the endpoint's hostname against it's identification
     * information.
     *
     * @param verifier hostname verifier.
     * @return an updated client builder instance.
     */
    public abstract ClientBuilder hostnameVerifier(final HostnameVerifier verifier);

    
Set the client-side ExecutorService. 

Provided executor service will be used for executing asynchronous tasks.


When running in a Jakarta EE container, implementations are required to use the container-managed executor service by
default. In Java SE, the default is implementation-specific. In either case, calling this method will override the
default.

Params:
  • executorService – executor service to be used for async invocations.
See Also:
Returns:an updated client builder instance.
Since:2.1
/**
     * Set the client-side {@link ExecutorService}.
     * <p>
     * Provided executor service will be used for executing asynchronous tasks.
     * <p>
     * When running in a Jakarta EE container, implementations are required to use the container-managed executor service by
     * default. In Java SE, the default is implementation-specific. In either case, calling this method will override the
     * default.
     *
     * @param executorService executor service to be used for async invocations.
     * @return an updated client builder instance.
     * @see Invocation.Builder#async()
     * @see Invocation.Builder#rx()
     * @see RxInvokerProvider#getRxInvoker(SyncInvoker, ExecutorService)
     * @since 2.1
     */
    public abstract ClientBuilder executorService(final ExecutorService executorService);

    
Set the client-side ScheduledExecutorService. 

Provided executor service will be used for executing scheduled asynchronous tasks.


When running in a Jakarta EE container, implementations are required to use the container-managed scheduled executor
service by default. In Java SE the default is implementation-specific. In either case, calling this method will
override the default.

Params:
  • scheduledExecutorService – executor service to be used for scheduled async invocations.
See Also:
Returns:an updated client builder instance.
Since:2.1
/**
     * Set the client-side {@link ScheduledExecutorService}.
     * <p>
     * Provided executor service will be used for executing scheduled asynchronous tasks.
     * <p>
     * When running in a Jakarta EE container, implementations are required to use the container-managed scheduled executor
     * service by default. In Java SE the default is implementation-specific. In either case, calling this method will
     * override the default.
     *
     * @param scheduledExecutorService executor service to be used for scheduled async invocations.
     * @return an updated client builder instance.
     * @see jakarta.ws.rs.sse.SseEventSource.Builder#reconnectingEvery(long, TimeUnit)
     * @since 2.1
     */
    public abstract ClientBuilder scheduledExecutorService(final ScheduledExecutorService scheduledExecutorService);

    
Set the connect timeout.

 Value 0 represents infinity. Negative values are not allowed. 
Params:
  • timeout – the maximum time to wait.
  • unit – the time unit of the timeout argument.
Throws:
Returns:an updated client builder instance.
Since:2.1
/**
     * Set the connect timeout.
     * <p>
     * Value {@code 0} represents infinity. Negative values are not allowed.
     *
     * @param timeout the maximum time to wait.
     * @param unit the time unit of the timeout argument.
     * @return an updated client builder instance.
     * @throws IllegalArgumentException when the value is negative.
     * @since 2.1
     */
    public abstract ClientBuilder connectTimeout(long timeout, TimeUnit unit);

    
Set the read timeout.

 The value is the timeout to read a response. If the server doesn't respond within the defined timeframe, ProcessingException is thrown with TimeoutException as a cause. 
 Value 0 represents infinity. Negative values are not allowed. 
Params:
  • timeout – the maximum time to wait.
  • unit – the time unit of the timeout argument.
Throws:
Returns:an updated client builder instance.
Since:2.1
/**
     * Set the read timeout.
     * <p>
     * The value is the timeout to read a response. If the server doesn't respond within the defined timeframe,
     * {@link ProcessingException} is thrown with {@link TimeoutException} as a cause.
     * <p>
     * Value {@code 0} represents infinity. Negative values are not allowed.
     *
     * @param timeout the maximum time to wait.
     * @param unit the time unit of the timeout argument.
     * @return an updated client builder instance.
     * @throws IllegalArgumentException when the value is negative.
     * @since 2.1
     */
    public abstract ClientBuilder readTimeout(long timeout, TimeUnit unit);

    
Build a new client instance using all the configuration previously specified in this client builder.

Returns:a new client instance.
/**
     * Build a new client instance using all the configuration previously specified in this client builder.
     *
     * @return a new client instance.
     */
    public abstract Client build();
}