/*
 * Copyright (c) 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 org.glassfish.jersey.client.spi;

import org.glassfish.jersey.Beta;
import org.glassfish.jersey.spi.Contract;

import javax.ws.rs.ConstrainedTo;
import javax.ws.rs.RuntimeType;
import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.CacheControl;
import javax.ws.rs.core.Configuration;
import javax.ws.rs.core.Cookie;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import java.net.URI;
import java.util.Collection;
import java.util.List;
import java.util.Locale;
import java.util.Map;

Implementations of this interface will be notified when a new Invocation.Builder is created. This will allow implementations to access the invocation builders, and is intended for global providers. For example, the Invocation.Builder properties can be accessed to set properties that are available on the ClientRequestContext. 
 In order for the InvocationBuilderListener to be called, the implementation of the interface needs to be registered on the Client the same way the ClientRequestFilter is registered, for instance. If multiple InvocationBuilderListeners are to be utilized, the order of execution is driven by the Priority, the lower the priority value, the higher the priority, the sooner the execution. 
Since:
2.30/**
 * Implementations of this interface will be notified when a new Invocation.Builder
 * is created. This will allow implementations to access the invocation builders,
 * and is intended for global providers. For example, the Invocation.Builder properties can be
 * accessed to set properties that are available on the {@link javax.ws.rs.client.ClientRequestContext}.
 * <p>
 * In order for the InvocationBuilderListener to be called, the implementation of the interface needs
 * to be registered on the {@code Client} the same way the {@code ClientRequestFilter} is registered, for instance.
 *
 * If multiple {@code InvocationBuilderListeners} are to be utilized, the order of execution is driven by the {@code Priority},
 * the lower the priority value, the higher the priority, the sooner the execution.
 *
 * @since 2.30
 */
@Beta
@Contract
@ConstrainedTo(RuntimeType.CLIENT)
public interface InvocationBuilderListener {

    
An Builder subset of setter methods. /**
     * An {@link javax.ws.rs.client.Invocation.Builder} subset of setter methods.
     */
    public interface InvocationBuilderContext {
        
Add the accepted response media types.
Params:
mediaTypes – accepted response media types.
Returns:
the updated context./**
         * Add the accepted response media types.
         *
         * @param mediaTypes accepted response media types.
         * @return the updated context.
         */
        InvocationBuilderContext accept(String... mediaTypes);

        
Add the accepted response media types.
Params:
mediaTypes – accepted response media types.
Returns:
the updated context./**
         * Add the accepted response media types.
         *
         * @param mediaTypes accepted response media types.
         * @return the updated context.
         */
        InvocationBuilderContext accept(MediaType... mediaTypes);

        
Add acceptable languages.
Params:
locales – an array of the acceptable languages.
Returns:
the updated context./**
         * Add acceptable languages.
         *
         * @param locales an array of the acceptable languages.
         * @return the updated context.
         */
        InvocationBuilderContext acceptLanguage(Locale... locales);

        
Add acceptable languages.
Params:
locales – an array of the acceptable languages.
Returns:
the updated context./**
         * Add acceptable languages.
         *
         * @param locales an array of the acceptable languages.
         * @return the updated context.
         */
        InvocationBuilderContext acceptLanguage(String... locales);

        
Add acceptable encodings.
Params:
encodings – an array of the acceptable encodings.
Returns:
the updated context./**
         * Add acceptable encodings.
         *
         * @param encodings an array of the acceptable encodings.
         * @return the updated context.
         */
        InvocationBuilderContext acceptEncoding(String... encodings);

        
Add a cookie to be set.
Params:
cookie – to be set.
Returns:
the updated context./**
         * Add a cookie to be set.
         *
         * @param cookie to be set.
         * @return the updated context.
         */
        InvocationBuilderContext cookie(Cookie cookie);

        
Add a cookie to be set.
Params:
name –  the name of the cookie.
value – the value of the cookie.
Returns:
the updated context./**
         * Add a cookie to be set.
         *
         * @param name  the name of the cookie.
         * @param value the value of the cookie.
         * @return the updated context.
         */
        InvocationBuilderContext cookie(String name, String value);

        
Set the cache control data of the message.
Params:
cacheControl – the cache control directives, if null any existing cache control directives will be removed.
Returns:
the updated context./**
         * Set the cache control data of the message.
         *
         * @param cacheControl the cache control directives, if {@code null}
         *                     any existing cache control directives will be removed.
         * @return the updated context.
         */
        InvocationBuilderContext cacheControl(CacheControl cacheControl);

        
Get the accepted response media types.
Returns:
accepted response media types./**
         * Get the accepted response media types.
         *
         * @return accepted response media types.
         */
        List<String> getAccepted();

        
Get acceptable languages.
Returns:
acceptable languages./**
         * Get acceptable languages.
         *
         * @return acceptable languages.
         */
        List<String> getAcceptedLanguages();

        
Get the cache control data of the message.
Returns:
the cache control data of the message./**
         * Get the cache control data of the message.
         *
         * @return the cache control data of the message.
         */
        List<CacheControl> getCacheControls();

        
Get runtime configuration.
Returns:
runtime configuration./**
         * Get runtime configuration.
         *
         * @return runtime configuration.
         */
        Configuration getConfiguration();

        
Get any cookies that accompanied the request.
Returns:
a read-only map of cookie name (String) to Cookie./**
         * Get any cookies that accompanied the request.
         *
         * @return a read-only map of cookie name (String) to {@link javax.ws.rs.core.Cookie}.
         */
        Map<String, Cookie> getCookies();

        
Get acceptable encodings.
Returns:
acceptable encodings./**
         * Get acceptable encodings.
         *
         * @return acceptable encodings.
         */
        List<String> getEncodings();

        
Get the values of a HTTP request header. The returned List is read-only.
Params:
name – the header name, case insensitive.
Returns:
a read-only list of header values./**
         * Get the values of a HTTP request header. The returned List is read-only.
         *
         * @param name the header name, case insensitive.
         * @return a read-only list of header values.
         */
        List<String> getHeader(String name);

        
Get the mutable message headers multivalued map.
Returns:
mutable multivalued map of message headers./**
         * Get the mutable message headers multivalued map.
         *
         * @return mutable multivalued map of message headers.
         */
        MultivaluedMap<String, Object> getHeaders();

        
Returns the property with the given name registered in the current request/response exchange context, or null if there is no property by that name. 

A property allows filters and interceptors to exchange
additional custom information not already provided by this interface.

 A list of supported properties can be retrieved using getPropertyNames(). Custom property names should follow the same convention as package names. 
Params:
name – a String specifying the name of the property.
See Also:
getPropertyNames()
Returns:
an Object containing the value of the property, or null if no property exists matching the given name./**
         * Returns the property with the given name registered in the current request/response
         * exchange context, or {@code null} if there is no property by that name.
         * <p>
         * A property allows filters and interceptors to exchange
         * additional custom information not already provided by this interface.
         * </p>
         * <p>
         * A list of supported properties can be retrieved using {@link #getPropertyNames()}.
         * Custom property names should follow the same convention as package names.
         * </p>
         *
         * @param name a {@code String} specifying the name of the property.
         * @return an {@code Object} containing the value of the property, or
         * {@code null} if no property exists matching the given name.
         * @see #getPropertyNames()
         */
        Object getProperty(String name);

        
Returns an immutable collection containing the property names available within the context of the current request/response exchange context. 
 Use the getProperty method with a property name to get the value of a property. 
See Also:
getProperty
Returns:
an immutable collection of property names./**
         * Returns an immutable {@link Collection collection} containing the property names
         * available within the context of the current request/response exchange context.
         * <p>
         * Use the {@link #getProperty} method with a property name to get the value of
         * a property.
         * </p>
         *
         * @return an immutable {@link Collection collection} of property names.
         * @see #getProperty
         */
        Collection<String> getPropertyNames();

        
Get the request URI.
Returns:
request URI./**
         * Get the request URI.
         *
         * @return request URI.
         */
        URI getUri();

        
Add an arbitrary header.
Params:
name –  the name of the header
value – the value of the header, the header will be serialized using a HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(Class<Object>) for the class of value or using its toString method if a header delegate is not available. If value is null then all current headers of the same name will be removed.
Returns:
the updated context./**
         * Add an arbitrary header.
         *
         * @param name  the name of the header
         * @param value the value of the header, the header will be serialized
         *              using a {@link javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate} if
         *              one is available via {@link javax.ws.rs.ext.RuntimeDelegate#createHeaderDelegate(java.lang.Class)}
         *              for the class of {@code value} or using its {@code toString} method
         *              if a header delegate is not available. If {@code value} is {@code null}
         *              then all current headers of the same name will be removed.
         * @return the updated context.
         */
        InvocationBuilderContext header(String name, Object value);

        
Replaces all existing headers with the newly supplied headers.
Params:
headers – new headers to be set, if null all existing headers will be removed.
Returns:
the updated context./**
         * Replaces all existing headers with the newly supplied headers.
         *
         * @param headers new headers to be set, if {@code null} all existing
         *                headers will be removed.
         * @return the updated context.
         */
        InvocationBuilderContext headers(MultivaluedMap<String, Object> headers);

        
Set a new property in the context of a request represented by this invocation builder.
 The property is available for a later retrieval via ClientRequestContext.getProperty(String) or InterceptorContext.getProperty(String). If a property with a given name is already set in the request context, the existing value of the property will be updated. Setting a null value into a property effectively removes the property from the request property bag. 
Params:
name –  property name.
value – (new) property value. null value removes the property with the given name.
See Also:
Invocation.property(String, Object)
Returns:
the updated context./**
         * Set a new property in the context of a request represented by this invocation builder.
         * <p>
         * The property is available for a later retrieval via {@link ClientRequestContext#getProperty(String)}
         * or {@link javax.ws.rs.ext.InterceptorContext#getProperty(String)}.
         * If a property with a given name is already set in the request context,
         * the existing value of the property will be updated.
         * Setting a {@code null} value into a property effectively removes the property
         * from the request property bag.
         * </p>
         *
         * @param name  property name.
         * @param value (new) property value. {@code null} value removes the property
         *              with the given name.
         * @return the updated context.
         * @see Invocation#property(String, Object)
         */
        InvocationBuilderContext property(String name, Object value);

        
Removes a property with the given name from the current request/response exchange context. After removal, subsequent calls to getProperty to retrieve the property value will return null. 
Params:
name – a String specifying the name of the property to be removed./**
         * Removes a property with the given name from the current request/response
         * exchange context. After removal, subsequent calls to {@link #getProperty}
         * to retrieve the property value will return {@code null}.
         *
         * @param name a {@code String} specifying the name of the property to be removed.
         */
        void removeProperty(String name);
    }

    
Whenever an Builder is created, (i.e. when WebTarget.request(), WebTarget.request(String...), WebTarget.request(MediaType...) is called), this method would be invoked. 
Params:
context – the updated InvocationBuilderContext./**
     * Whenever an {@link Invocation.Builder} is created, (i.e. when
     * {@link WebTarget#request()}, {@link WebTarget#request(String...)},
     * {@link WebTarget#request(MediaType...)} is called), this method would be invoked.
     *
     * @param context the updated {@link InvocationBuilderContext}.
     */
    void onNewBuilder(InvocationBuilderContext context);

}