/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.apache.qpid.protonj2.client.transport;

import java.io.IOException;
import java.net.URI;
import java.security.Principal;

import org.apache.qpid.protonj2.buffer.ProtonBuffer;
import org.apache.qpid.protonj2.buffer.ProtonBufferAllocator;
import org.apache.qpid.protonj2.client.SslOptions;
import org.apache.qpid.protonj2.client.TransportOptions;

/**
 * Base class for all QpidJMS Transport instances.
 */
public interface Transport {

    /**
     * Performs the connect operation for the implemented Transport type such as
     * a TCP socket connection, SSL/TLS handshake etc.  The connection operation
     * itself will be performed as an asynchronous operation with the success or
     * failure being communicated to the event point
     * {@link TransportListener#transportError(Throwable)}.  If the users wishes
     * to perform a block on connect outcome the {@link #awaitConnect()} method
     * will wait for and or throw an error based on the connect outcome.
     *
     * @param host
     *      The remote host that this {@link Transport} should attempt to connect to.
     * @param port
     *      The port on the remote host that this {@link Transport} should attempt to bind to.
     * @param listener
     *      The {@link TransportListener} that will handle {@link Transport} events.
     *
     * @return this {@link Transport} instance.
     *
     * @throws IOException if an error occurs while attempting the connect.
     */
    Transport connect(String host, int port, TransportListener listener) throws IOException;

    /**
     * Waits interruptibly for the {@link Transport} to connect to the remote that was
     * indicated in the {@link #connect(String, int, TransportListener)} call.
     *
     * @throws InterruptedException
     *      If the wait mechanism was interrupted while waiting for a successful connect.
     * @throws IOException
     *      If the {@link Transport} failed to connect or was closed before connected.
     */
    void awaitConnect() throws InterruptedException, IOException;

    /**
     * @return true if transport is connected or false if the connection is down.
     */
    boolean isConnected();

    /**
     * @return true if transport is connected using a secured channel (SSL).
     */
    boolean isSecure();

    /**
     * Close the Transport, no additional send operations are accepted.
     *
     * @throws IOException if an error occurs while closing the connection.
     */
    void close() throws IOException;

    /**
     * Gets a buffer allocator that can produce {@link ProtonBuffer} instance that may be
     * optimized for use with the underlying transport implementation.
     *
     * @return a {@link ProtonBufferAllocator} that creates transport friendly buffers.
     */
    ProtonBufferAllocator getBufferAllocator();

    /**
     * Writes a chunk of data over the Transport connection without performing an
     * explicit flush on the transport.
     *
     * @param output
     *        The buffer of data that is to be transmitted.
     *
     * @return this {@link Transport} instance.
     *
     * @throws IOException if an error occurs during the write operation.
     */
    Transport write(ProtonBuffer output) throws IOException;

    /**
     * Writes a chunk of data over the Transport connection without performing an
     * explicit flush on the transport.  This method allows for a completion callback
     * that is signaled when the actual low level IO operation is completed which could
     * be after this method has returned.
     *
     * @param output
     *        The buffer of data that is to be transmitted.
     * @param ioComplete
     *        A {@link Runnable} that is invoked when the IO operation completes successfully.
     *
     * @return this {@link Transport} instance.
     *
     * @throws IOException if an error occurs during the write operation.
     */
    Transport write(ProtonBuffer output, Runnable ioComplete) throws IOException;

    /**
     * Writes a chunk of data over the Transport connection and requests a flush of
     * all pending queued write operations
     *
     * @param output
     *        The buffer of data that is to be transmitted.
     *
     * @return this {@link Transport} instance.
     *
     * @throws IOException if an error occurs during the write operation.
     */
    Transport writeAndFlush(ProtonBuffer output) throws IOException;

    /**
     * Writes a chunk of data over the Transport connection and requests a flush of
     * all pending queued write operations
     *
     * @param output
     *        The buffer of data that is to be transmitted.
     * @param ioComplete
     *        A {@link Runnable} that is invoked when the IO operation completes successfully.
     *
     * @return this {@link Transport} instance.
     *
     * @throws IOException if an error occurs during the write operation.
     */
    Transport writeAndFlush(ProtonBuffer output, Runnable ioComplete) throws IOException;

    /**
     * Request a flush of all pending writes to the underlying connection.
     *
     * @return this {@link Transport} instance.
     *
     * @throws IOException if an error occurs during the flush operation.
     */
    Transport flush() throws IOException;

    /**
     * Gets the currently set TransportListener instance
     *
     * @return the current TransportListener or null if none set.
     */
    TransportListener getTransportListener();

    /**
     * @return a {@link TransportOptions} instance copied from the immutable options given at create time..
     */
    TransportOptions getTransportOptions();

    /**
     * @return a {@link SslOptions} instance copied from the immutable options given at create time..
     */
    SslOptions getSslOptions();

    /**
     * @return the host name or IP address that the transport connects to.
     */
    String getHost();

    /**
     * @return the port that the transport connects to.
     */
    int getPort();

    /**
     * Returns a URI that contains some meaningful information about the remote connection such as a
     * scheme that reflects the transport type and the remote host and port that the connection was
     * instructed to connect to.  If called before the {@link #connect(String, int, TransportListener)}
     * method this method returns <code>null</code>.
     *
     * @return a URI that reflects a meaningful view of the {@link Transport} remote connection details.
     */
    URI getRemoteURI();

    /**
     * @return the local principal for a Transport that is using a secure connection.
     */
    Principal getLocalPrincipal();

}