/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2014 Red Hat, Inc., and individual contributors
 * as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package io.undertow.client;

import io.undertow.UndertowMessages;
import org.xnio.ChannelListener;
import org.xnio.Option;
import io.undertow.connector.ByteBufferPool;
import org.xnio.StreamConnection;
import org.xnio.XnioIoThread;
import org.xnio.XnioWorker;

import java.io.IOException;
import java.net.SocketAddress;
import java.nio.channels.Channel;
import java.util.concurrent.TimeUnit;

A client connection. This can be used to send requests, or to upgrade the connection.

In general these objects are not thread safe, they should only be used by the IO thread
that is responsible for the connection. As a result this client does not provide a mechanism
to perform blocking IO, it is designed for async operation only.
Author:
Stuart Douglas/**
 * A client connection. This can be used to send requests, or to upgrade the connection.
 * <p>
 * In general these objects are not thread safe, they should only be used by the IO thread
 * that is responsible for the connection. As a result this client does not provide a mechanism
 * to perform blocking IO, it is designed for async operation only.
 *
 * @author Stuart Douglas
 */
public interface ClientConnection extends Channel {

    
Sends a client request. The request object should not be modified after it has been submitted to the connection.
 Request objects can be queued. Once the request is in a state that it is ready to be sent the clientCallback is invoked to provide the caller with the ClientExchange 
 If isMultiplexingSupported() returns true then multiple requests may be active at the same time, and a later request may complete before an earlier one. 

Note that the request header may not be written out until after the callback has been invoked. This allows the
client to write out a header with a gathering write if the request contains content.
Params:
request – The request to send./**
     * Sends a client request. The request object should not be modified after it has been submitted to the connection.
     * <p>
     * Request objects can be queued. Once the request is in a state that it is ready to be sent the {@code clientCallback}
     * is invoked to provide the caller with the {@link ClientExchange}
     * <p>
     * If {@link #isMultiplexingSupported()} returns true then multiple requests may be active at the same time, and a later
     * request may complete before an earlier one.
     * <p>
     * Note that the request header may not be written out until after the callback has been invoked. This allows the
     * client to write out a header with a gathering write if the request contains content.
     *
     * @param request The request to send.
     */
    void sendRequest(final ClientRequest request, final ClientCallback<ClientExchange> clientCallback);

    
Upgrade the connection, if the underlying protocol supports it. This should only be called after an upgrade request
has been submitted and the target server has accepted the upgrade.
Returns:
The resulting StreamConnection/**
     * Upgrade the connection, if the underlying protocol supports it. This should only be called after an upgrade request
     * has been submitted and the target server has accepted the upgrade.
     *
     * @return The resulting StreamConnection
     */
    StreamConnection performUpgrade() throws IOException;

    
Returns:
The buffer pool used by the client/**
     *
     * @return The buffer pool used by the client
     */
    ByteBufferPool getBufferPool();

    SocketAddress getPeerAddress();

    <A extends SocketAddress> A getPeerAddress(Class<A> type);

    ChannelListener.Setter<? extends ClientConnection> getCloseSetter();

    SocketAddress getLocalAddress();

    <A extends SocketAddress> A getLocalAddress(Class<A> type);

    XnioWorker getWorker();

    XnioIoThread getIoThread();

    boolean isOpen();

    boolean supportsOption(Option<?> option);

    <T> T getOption(Option<T> option) throws IOException;

    <T> T setOption(Option<T> option, T value) throws IllegalArgumentException, IOException;

    boolean isUpgraded();

    
Returns:
true if this connection support server push/**
     *
     * @return <code>true</code> if this connection support server push
     */
    boolean isPushSupported();

    
Returns:
true if this client supports multiplexing/**
     *
     * @return <code>true</code> if this client supports multiplexing
     */
    boolean isMultiplexingSupported();

    
Returns:
the statistics information, or null if statistics are not supported or disabled/**
     *
     * @return the statistics information, or <code>null</code> if statistics are not supported or disabled
     */
    ClientStatistics getStatistics();

    boolean isUpgradeSupported();

    
Adds a close listener, than will be invoked with the connection is closed
Params:
listener – The close listener/**
     * Adds a close listener, than will be invoked with the connection is closed
     *
     * @param listener The close listener
     */
    void addCloseListener(ChannelListener<ClientConnection> listener);

    
Returns:
true if the underlying protocol supports sending a ping/**
     *
     * @return <code>true</code> if the underlying protocol supports sending a ping
     */
    default boolean isPingSupported() {
        return false;
    }

    default void sendPing(PingListener listener, long timeout, TimeUnit timeUnit) {
        listener.failed(UndertowMessages.MESSAGES.pingNotSupported());
    }

    interface PingListener {

        void acknowledged();

        void failed(IOException e);

    }
}