/*
 * Copyright (c) 2008, 2017 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.grizzly;

import java.io.IOException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

import org.glassfish.grizzly.attributes.AttributeStorage;
import org.glassfish.grizzly.memory.MemoryManager;
import org.glassfish.grizzly.monitoring.MonitoringAware;
import org.glassfish.grizzly.monitoring.MonitoringConfig;
import org.glassfish.grizzly.utils.NullaryFunction;

Common interface, which represents any kind of connection.
Author:
Alexey Stashok
Type parameters:
<L> – the Connection address type/**
 * Common interface, which represents any kind of connection.
 * 
 * @param <L> the Connection address type
 * 
 * @author Alexey Stashok
 */
public interface Connection<L> extends Readable<L>, Writeable<L>,
        Closeable, AttributeStorage,
        MonitoringAware<ConnectionProbe> {
    
Get the Transport, to which this Connection belongs to. 
Returns:
the Transport, to which this Connection belongs to./**
     * Get the {@link Transport}, to which this {@link Connection} belongs to.
     * @return the {@link Transport}, to which this {@link Connection} belongs to.
     */
    Transport getTransport();

    
Is Connection open and ready. Returns true, if connection is open and ready, or false
otherwise.
Returns:
true, if connection is open and ready, or false
otherwise./**
     * Is {@link Connection} open and ready.
     * Returns <tt>true</tt>, if connection is open and ready, or <tt>false</tt>
     * otherwise.
     * 
     * @return <tt>true</tt>, if connection is open and ready, or <tt>false</tt>
     * otherwise.
     */
    @Override
    boolean isOpen();

    
Checks if this Connection is open and ready to be used.
If this Connection is closed - this method throws IOException giving the reason why this Connection
was closed.
Throws:
IOException – /**
     * Checks if this <tt>Connection</tt> is open and ready to be used.
     * If this <tt>Connection</tt> is closed - this method throws
     * {@link IOException} giving the reason why this <tt>Connection</tt>
     * was closed.
     * 
     * @throws IOException 
     */
    @Override
    void assertOpen() throws IOException;
    
    
Returns CloseReason if this Connection has been closed,
or null otherwise.
Returns:
CloseReason if this Connection has been closed,
or null otherwise/**
     * Returns {@link CloseReason} if this <tt>Connection</tt> has been closed,
     * or <tt>null</tt> otherwise.
     * 
     * @return {@link CloseReason} if this <tt>Connection</tt> has been closed,
     * or <tt>null</tt> otherwise
     */
    CloseReason getCloseReason();
    
    
Sets the Connection mode. 
Params:
isBlocking – the Connection mode. true, if Connection should operate in blocking mode, or false otherwise./**
     * Sets the {@link Connection} mode.
     *
     * @param isBlocking the {@link Connection} mode. <tt>true</tt>,
     * if {@link Connection} should operate in blocking mode, or
     * <tt>false</tt> otherwise.
     */
    void configureBlocking(boolean isBlocking);

    
Returns:
the Connection mode. true, if Connection is operating in blocking mode, or false otherwise./**
     * @return the {@link Connection} mode.
     * <tt>true</tt>, if {@link Connection} is operating in blocking mode, or
     * <tt>false</tt> otherwise.
     */
    boolean isBlocking();

    @Deprecated
    void configureStandalone(boolean isStandalone);

    @Deprecated
    boolean isStandalone();

    
Gets the Processor, which will process Connection I/O event. If Processor is null, - then Transport will try to get Processor using Connection's ProcessorSelector.select(IOEvent, Connection). If ProcessorSelector, associated withthe Connection is also null - will ask Transport for a Processor. 
Params:
ioEvent – 
Returns:
the default Processor, which will process Connection I/O events./**
     * Gets the {@link Processor}, which will process {@link Connection}
     * I/O event.
     * If {@link Processor} is <tt>null</tt>,  - then {@link Transport} will try
     * to get {@link Processor} using {@link Connection}'s
     * {@link ProcessorSelector#select(IOEvent, Connection)}. If
     * {@link ProcessorSelector}, associated withthe {@link Connection} is also
     * <tt>null</tt> - will ask {@link Transport} for a {@link Processor}.
     *
     * @param ioEvent
     * @return the default {@link Processor}, which will process
     * {@link Connection} I/O events.
     */
    Processor obtainProcessor(IOEvent ioEvent);
    
    
Gets the default Processor, which will process Connection I/O events. If Processor is null, - then Transport will try to get Processor using Connection's ProcessorSelector.select(IOEvent, Connection). If ProcessorSelector, associated withthe Connection is also null - Transport will try to get Processor using own settings. 
Returns:
the default Processor, which will process Connection I/O events./**
     * Gets the default {@link Processor}, which will process {@link Connection}
     * I/O events.
     * If {@link Processor} is <tt>null</tt>,  - then {@link Transport} will try
     * to get {@link Processor} using {@link Connection}'s
     * {@link ProcessorSelector#select(IOEvent, Connection)}. If
     * {@link ProcessorSelector}, associated withthe {@link Connection} is also
     * <tt>null</tt> - {@link Transport} will try to get {@link Processor}
     * using own settings.
     *
     * @return the default {@link Processor}, which will process
     * {@link Connection} I/O events.
     */
    Processor getProcessor();

    
Sets the default Processor, which will process Connection I/O events. If Processor is null, - then Transport will try to get Processor using Connection's ProcessorSelector.select(IOEvent, Connection). If ProcessorSelector, associated withthe Connection is also null - Transport will try to get Processor using own settings. 
Params:
preferableProcessor – the default Processor, which will process Connection I/O events./**
     * Sets the default {@link Processor}, which will process {@link Connection}
     * I/O events.
     * If {@link Processor} is <tt>null</tt>,  - then {@link Transport} will try
     * to get {@link Processor} using {@link Connection}'s
     * {@link ProcessorSelector#select(IOEvent, Connection)}. If
     * {@link ProcessorSelector}, associated withthe {@link Connection} is also
     * <tt>null</tt> - {@link Transport} will try to get {@link Processor}
     * using own settings.
     *
     * @param preferableProcessor the default {@link Processor}, which will
     * process {@link Connection} I/O events.
     */
    void setProcessor(
        Processor preferableProcessor);

    
Gets the default ProcessorSelector, which will be used to get Processor to process Connection I/O events, in case if this Connection's Processor is null.
Returns:
the default ProcessorSelector, which will be used to get Processor to process Connection I/O events, in case if this Connection's Processor is null./**
     * Gets the default {@link ProcessorSelector}, which will be used to get
     * {@link Processor} to process {@link Connection} I/O events, in case if
     * this {@link Connection}'s {@link Processor} is <tt>null</tt>.
     *
     * @return the default {@link ProcessorSelector}, which will be used to get
     * {@link Processor} to process {@link Connection} I/O events, in case if
     * this {@link Connection}'s {@link Processor} is <tt>null</tt>.
     */
    ProcessorSelector getProcessorSelector();
    
    
Sets the default ProcessorSelector, which will be used to get Processor to process Connection I/O events, in case if this Connection's Processor is null.
Params:
preferableProcessorSelector – the default ProcessorSelector, which will be used to get Processor to process Connection I/O events, in case if this Connection's Processor is null./**
     * Sets the default {@link ProcessorSelector}, which will be used to get
     * {@link Processor} to process {@link Connection} I/O events, in case if
     * this {@link Connection}'s {@link Processor} is <tt>null</tt>.
     *
     * @param preferableProcessorSelector the default {@link ProcessorSelector},
     * which will be used to get {@link Processor} to process {@link Connection}
     * I/O events, in case if this {@link Connection}'s {@link Processor}
     * is <tt>null</tt>.
     */
    void setProcessorSelector(
        ProcessorSelector preferableProcessorSelector);

    
Returns the Processor state associated with this Connection.
Params:
processor – Processor
factory – 
Type parameters:
<E> – 
Returns:
the Processor state associated with this Connection./**
     * Returns the {@link Processor} state associated with this <tt>Connection</tt>.
     * @param <E>
     * @param processor {@link Processor}
     * @param factory
     * 
     * @return the {@link Processor} state associated with this <tt>Connection</tt>.
     */
    <E> E obtainProcessorState(Processor processor,
            NullaryFunction<E> factory);
    
    
Executes the Runnable in the thread, responsible for running the given type of event on this Connection. The thread will be chosen based on Transport settings, especially current I/O strategy. 
Params:
event – 
runnable – /**
     * Executes the {@link Runnable} in the thread, responsible for running
     * the given type of event on this <tt>Connection</tt>.
     * The thread will be chosen based on {@link #getTransport() Transport}
     * settings, especially current I/O strategy.
     * 
     * @param event
     * @param runnable 
     */
    void executeInEventThread(IOEvent event, Runnable runnable);
    
    
Returns:
an associated MemoryManager. It's a shortcut for #getTransport()#getMemoryManager()
Since:
2.3.18/**
     * @return an associated {@link MemoryManager}. It's a shortcut for {@link #getTransport()#getMemoryManager()}
     * @since 2.3.18
     */
    MemoryManager<?> getMemoryManager();
    
    
Get the connection peer address
Returns:
the connection peer address/**
     * Get the connection peer address
     * @return the connection peer address
     */
    L getPeerAddress();
    
    
Get the connection local address
Returns:
the connection local address/**
     * Get the connection local address
     * @return the connection local address
     */
    L getLocalAddress();

    
Get the default size of Buffers, which will be allocated for reading data from Connection. The value less or equal to zero will be ignored. 
Returns:
the default size of Buffers, which will be allocated for reading data from Connection./**
     * Get the default size of {@link Buffer}s, which will be allocated for
     * reading data from {@link Connection}.
     * The value less or equal to zero will be ignored.
     *
     * @return the default size of {@link Buffer}s, which will be allocated for
     * reading data from {@link Connection}.
     */
    int getReadBufferSize();

    
Set the default size of Buffers, which will be allocated for reading data from Connection. The value less or equal to zero will be ignored. 
Params:
readBufferSize – the default size of Buffers, which will be allocated for reading data from Connection./**
     * Set the default size of {@link Buffer}s, which will be allocated for
     * reading data from {@link Connection}.
     * The value less or equal to zero will be ignored.
     *
     * @param readBufferSize the default size of {@link Buffer}s, which will
     * be allocated for reading data from {@link Connection}.
     */
    void setReadBufferSize(int readBufferSize);

    
Get the default size of Buffers, which will be allocated for writing data to Connection. 
Returns:
the default size of Buffers, which will be allocated for writing data to Connection./**
     * Get the default size of {@link Buffer}s, which will be allocated for
     * writing data to {@link Connection}.
     *
     * @return the default size of {@link Buffer}s, which will be allocated for
     * writing data to {@link Connection}.
     */
    int getWriteBufferSize();

    
Set the default size of Buffers, which will be allocated for writing data to Connection. 
Params:
writeBufferSize – the default size of Buffers, which will be allocated for writing data to Connection./**
     * Set the default size of {@link Buffer}s, which will be allocated for
     * writing data to {@link Connection}.
     *
     * @param writeBufferSize the default size of {@link Buffer}s, which will
     * be allocated for writing data to {@link Connection}.
     */
    void setWriteBufferSize(int writeBufferSize);

    
Get the max size (in bytes) of asynchronous write queue associated
with connection.
Returns:
the max size (in bytes) of asynchronous write queue associated
with connection.
Since:
2.2/**
     * Get the max size (in bytes) of asynchronous write queue associated
     * with connection.
     * 
     * @return the max size (in bytes) of asynchronous write queue associated
     * with connection.
     * 
     * @since 2.2
     */
    int getMaxAsyncWriteQueueSize();

    
Set the max size (in bytes) of asynchronous write queue associated
with connection.
Params:
maxAsyncWriteQueueSize – the max size (in bytes) of asynchronous
write queue associated with connection.
Since:
2.2/**
     * Set the max size (in bytes) of asynchronous write queue associated
     * with connection.
     * 
     * @param maxAsyncWriteQueueSize the max size (in bytes) of asynchronous
     * write queue associated with connection.
     * 
     * @since 2.2
     */
    void setMaxAsyncWriteQueueSize(int maxAsyncWriteQueueSize);
    
    
Returns the current value for the blocking read timeout converted to the provided TimeUnit specification. If this value hasn't been explicitly set, it will default to DEFAULT_READ_TIMEOUT seconds. 
Params:
timeUnit – the TimeUnit to convert the returned result to.
Since:
2.3/**
     * Returns the current value for the blocking read timeout converted to the
     * provided {@link TimeUnit} specification.  If this value hasn't been
     * explicitly set, it will default to {@value #DEFAULT_READ_TIMEOUT} seconds.
     *
     * @param timeUnit the {@link TimeUnit} to convert the returned result to.
     *
     * @since 2.3
     */
    long getReadTimeout(TimeUnit timeUnit);

    
Specifies the timeout for the blocking reads.  This may be overridden on
a per-connection basis.
A value of zero or less effectively disables the timeout.
Params:
timeout – the new timeout value
timeUnit – the {@TimeUnit} specification of the provided value.
See Also:
setReadTimeout(long, TimeUnit)
Since:
2.3/**
     * Specifies the timeout for the blocking reads.  This may be overridden on
     * a per-connection basis.
     * A value of zero or less effectively disables the timeout.
     *
     * @param timeout the new timeout value
     * @param timeUnit the {@TimeUnit} specification of the provided value.
     *
     * @see Connection#setReadTimeout(long, java.util.concurrent.TimeUnit)
     *
     * @since 2.3
     */
    void setReadTimeout(long timeout, TimeUnit timeUnit);

    
Returns the current value for the blocking write timeout converted to the provided TimeUnit specification. If this value hasn't been explicitly set, it will default to DEFAULT_WRITE_TIMEOUT seconds. 
Params:
timeUnit – the TimeUnit to convert the returned result to.
Since:
2.3/**
     * Returns the current value for the blocking write timeout converted to the
     * provided {@link TimeUnit} specification.  If this value hasn't been
     * explicitly set, it will default to {@value #DEFAULT_WRITE_TIMEOUT} seconds.
     *
     * @param timeUnit the {@link TimeUnit} to convert the returned result to.
     *
     * @since 2.3
     */
    long getWriteTimeout(TimeUnit timeUnit);

    
Specifies the timeout for the blocking writes.  This may be overridden on
a per-connection basis.
A value of zero or less effectively disables the timeout.
Params:
timeout –  the new timeout value
timeUnit – the {@TimeUnit} specification of the provided value.
See Also:
setWriteTimeout(long, TimeUnit)
Since:
2.3/**
     * Specifies the timeout for the blocking writes.  This may be overridden on
     * a per-connection basis.
     * A value of zero or less effectively disables the timeout.
     *
     * @param timeout  the new timeout value
     * @param timeUnit the {@TimeUnit} specification of the provided value.
     *
     * @see Connection#setWriteTimeout(long, java.util.concurrent.TimeUnit)
     *
     * @since 2.3
     */
    void setWriteTimeout(long timeout, TimeUnit timeUnit);

    void simulateIOEvent(final IOEvent ioEvent) throws IOException;

    void enableIOEvent(final IOEvent ioEvent) throws IOException;

    void disableIOEvent(final IOEvent ioEvent) throws IOException;
    
    
Returns:
the Connection monitoring configuration MonitoringConfig./**
     * @return the <tt>Connection</tt> monitoring configuration {@link MonitoringConfig}.
     */
    @Override
    MonitoringConfig<ConnectionProbe> getMonitoringConfig();

    
Close the Connection silently, no notification required on completion or failure. /**
     * Close the {@link Connection} silently, no notification required on
     * completion or failure.
     */
    @Override
    void terminateSilently();

    
Close the Connection 
Returns:
Future, which could be checked in case, if close operation will be run asynchronously/**
     * Close the {@link Connection}
     *
     * @return {@link Future}, which could be checked in case, if close operation
     *         will be run asynchronously
     */
    @Override
    GrizzlyFuture<Closeable> terminate();
    
    
Closes the Connection and provides the reason description. This method is similar to terminateSilently(), but additionally provides the reason why the Connection will be closed.
Params:
reason – /**
     * Closes the <tt>Connection</tt> and provides the reason description.
     * 
     * This method is similar to {@link #terminateSilently()}, but additionally
     * provides the reason why the <tt>Connection</tt> will be closed.
     * 
     * @param reason 
     */
    @Override
    void terminateWithReason(IOException reason);
    
    
Gracefully close the Connection 
Returns:
Future, which could be checked in case, if close operation will be run asynchronously/**
     * Gracefully close the {@link Connection}
     *
     * @return {@link Future}, which could be checked in case, if close operation
     *         will be run asynchronously
     */
    @Override
    GrizzlyFuture<Closeable> close();

    
Gracefully close the Connection 
Params:
completionHandler – CompletionHandler to be called, when the connection is closed.
Deprecated:
use close() with the following GrizzlyFuture.addCompletionHandler(CompletionHandler)./**
     * Gracefully close the {@link Connection}
     *
     * @param completionHandler {@link CompletionHandler} to be called, when
     *  the connection is closed.
     * 
     * @deprecated use {@link #close()} with the following {@link GrizzlyFuture#addCompletionHandler(org.glassfish.grizzly.CompletionHandler)}.
     */
    @Override
    void close(CompletionHandler<Closeable> completionHandler);

    
Gracefully close the Connection silently, no notification required on completion or failure. /**
     * Gracefully close the {@link Connection} silently, no notification required on
     * completion or failure.
     */
    @Override
    void closeSilently();

    
Gracefully closes the Connection and provides the reason description. This method is similar to closeSilently(), but additionally provides the reason why the Connection will be closed.
Params:
reason – /**
     * Gracefully closes the <tt>Connection</tt> and provides the reason description.
     * 
     * This method is similar to {@link #closeSilently()}, but additionally
     * provides the reason why the <tt>Connection</tt> will be closed.
     * 
     * @param reason 
     */
    @Override
    void closeWithReason(IOException reason);
    
    
Add the CloseListener, which will be notified once Connection
will be closed.
Params:
closeListener – CloseListener.
Since:
2.3/**
     * Add the {@link CloseListener}, which will be notified once <tt>Connection</tt>
     * will be closed.
     * 
     * @param closeListener {@link CloseListener}.
     *
     * @since 2.3
     */
    @Override
    void addCloseListener(org.glassfish.grizzly.CloseListener closeListener);

    
Remove the CloseListener. 
Params:
closeListener – CloseListener.
Since:
2.3/**
     * Remove the {@link CloseListener}.
     *
     * @param closeListener {@link CloseListener}.
     *
     * @since 2.3
     */
    @Override
    boolean removeCloseListener(org.glassfish.grizzly.CloseListener closeListener);

    
Add the CloseListener, which will be notified once Connection
will be closed.
Params:
closeListener – CloseListener
Deprecated:
use addCloseListener(CloseListener)/**
     * Add the {@link CloseListener}, which will be notified once <tt>Connection</tt>
     * will be closed.
     * @param closeListener {@link CloseListener}
     *
     * @deprecated use {@link #addCloseListener(org.glassfish.grizzly.CloseListener)}
     */
    @Deprecated
    void addCloseListener(CloseListener closeListener);

    
Remove the CloseListener. 
Params:
closeListener – CloseListener.
Deprecated:
use removeCloseListener(CloseListener)/**
     * Remove the {@link CloseListener}.
     *
     * @param closeListener {@link CloseListener}.
     *
     * @deprecated use {@link #removeCloseListener(org.glassfish.grizzly.CloseListener)}
     */
    @Deprecated
    boolean removeCloseListener(CloseListener closeListener);
    
    
Method gets invoked, when error occur during the Connection lifecycle.
Params:
error – Throwable./**
     * Method gets invoked, when error occur during the <tt>Connection</tt> lifecycle.
     *
     * @param error {@link Throwable}.
     */
    void notifyConnectionError(Throwable error);


    // ------------------------------------------------------------------- Nested Classes

    
This interface will be removed in 3.0.
See Also:
GenericCloseListener
Deprecated:
use CloseListener/**
     * This interface will be removed in 3.0.
     *
     * @deprecated use {@link org.glassfish.grizzly.CloseListener}
     *
     * @see GenericCloseListener
     */
    @Deprecated
    interface CloseListener extends org.glassfish.grizzly.CloseListener<Connection, CloseType> {

        @Override
        void onClosed(Connection connection, CloseType type) throws IOException;

    }

    
This enum will be removed in 3.0.
Deprecated:
use CloseType/**
     * This enum will be removed in 3.0.
     *
     * @deprecated use {@link org.glassfish.grizzly.CloseType}
     */
    @Deprecated
    enum CloseType implements ICloseType {
        LOCALLY, REMOTELY
    }

}