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

import org.glassfish.grizzly.Buffer;
import org.glassfish.grizzly.CompletionHandler;
import org.glassfish.grizzly.Connection;
import org.glassfish.grizzly.WriteHandler;
import org.glassfish.grizzly.WriteResult;
import org.glassfish.grizzly.Writer;
import org.glassfish.grizzly.nio.NIOConnection;

The AsyncQueue, which implements asynchronous write queue. 
Author:
Alexey Stashok, Ryan Lubke
Type parameters:
<L> – the destination address type/**
 * The {@link AsyncQueue}, which implements asynchronous write queue.
 *
 * @param <L> the destination address type
 *
 * @author Alexey Stashok
 * @author Ryan Lubke
 */
@SuppressWarnings("deprecation")
public interface AsyncQueueWriter<L> extends Writer<L>, AsyncQueue {

    
Constant set via setMaxPendingBytesPerConnection(int) means the async write queue size is unlimited. /**
     * Constant set via {@link #setMaxPendingBytesPerConnection(int)} means the async write queue size is unlimited.
     */
    int UNLIMITED_SIZE = -1;

    
Constant set via setMaxPendingBytesPerConnection(int) means the async write queue size will be configured automatically per NIOConnection depending on connections write buffer size. /**
     * Constant set via {@link #setMaxPendingBytesPerConnection(int)} means the async write queue size will be configured
     * automatically per {@link NIOConnection} depending on connections write buffer size.
     */
    int AUTO_SIZE = -2;

    
Method writes the Buffer to the specific address. 
Params:
connection – the Connection to write to
dstAddress – the destination address the WritableMessage will be sent to
message – the WritableMessage, from which the data will be written
completionHandler – CompletionHandler, which will get notified, when write will be completed
pushBackHandler – PushBackHandler, which will be notified if message was accepted by transport write queue or refused
cloner – MessageCloner, which will be invoked by AsyncQueueWriter, if message could not be
written to a channel directly and has to be put on a asynchronous queue
Deprecated:
push back logic is deprecated/**
     * Method writes the {@link Buffer} to the specific address.
     *
     *
     * @param connection the {@link org.glassfish.grizzly.Connection} to write to
     * @param dstAddress the destination address the {@link WritableMessage} will be sent to
     * @param message the {@link WritableMessage}, from which the data will be written
     * @param completionHandler {@link org.glassfish.grizzly.CompletionHandler}, which will get notified, when write will be
     * completed
     * @param pushBackHandler {@link PushBackHandler}, which will be notified if message was accepted by transport write
     * queue or refused
     * @param cloner {@link MessageCloner}, which will be invoked by <tt>AsyncQueueWriter</tt>, if message could not be
     * written to a channel directly and has to be put on a asynchronous queue
     *
     * @deprecated push back logic is deprecated
     */
    @Deprecated
    void write(Connection<L> connection, L dstAddress, WritableMessage message, CompletionHandler<WriteResult<WritableMessage, L>> completionHandler,
            PushBackHandler pushBackHandler, MessageCloner<WritableMessage> cloner);

    
Params:
connection – the Connection to test whether or not the specified number of bytes can be written to.
size – number of bytes to write.
Returns:
true if the queue has not exceeded it's maximum size in bytes of pending writes, otherwise
false
Since:
2.2
Deprecated:
the size parameter will be ignored, use Writer.canWrite(Connection) instead./**
     * @param connection the {@link Connection} to test whether or not the specified number of bytes can be written to.
     * @param size number of bytes to write.
     * @return <code>true</code> if the queue has not exceeded it's maximum size in bytes of pending writes, otherwise
     * <code>false</code>
     *
     * @since 2.2
     * @deprecated the size parameter will be ignored, use {@link #canWrite(org.glassfish.grizzly.Connection)} instead.
     */
    @Deprecated
    boolean canWrite(final Connection<L> connection, int size);

    
Registers WriteHandler, which will be notified ones the Connection is able to accept more bytes to be written. Note: using this method from different threads simultaneously may lead to quick situation changes, so at time WriteHandler is called - the queue may become busy again. 
Params:
connection – Connection
writeHandler – WriteHandler to be notified.
size – number of bytes queue has to be able to accept before notifying WriteHandler.
Since:
2.2
Deprecated:
the size parameter will be ignored, use instead./**
     * Registers {@link WriteHandler}, which will be notified ones the {@link Connection} is able to accept more bytes to be
     * written. Note: using this method from different threads simultaneously may lead to quick situation changes, so at
     * time {@link WriteHandler} is called - the queue may become busy again.
     *
     * @param connection {@link Connection}
     * @param writeHandler {@link WriteHandler} to be notified.
     * @param size number of bytes queue has to be able to accept before notifying {@link WriteHandler}.
     *
     * @since 2.2
     * @deprecated the size parameter will be ignored, use
     * {@link #notifyWritePossible(org.glassfish.grizzly.Connection, org.glassfish.grizzly.WriteHandler) instead.
     */
    @Deprecated
    void notifyWritePossible(final Connection<L> connection, final WriteHandler writeHandler, final int size);

    
Configures the maximum number of bytes pending to be written for a particular Connection. 
Params:
maxQueuedWrites – maximum number of bytes that may be pending to be written to a particular Connection./**
     * Configures the maximum number of bytes pending to be written for a particular {@link Connection}.
     *
     * @param maxQueuedWrites maximum number of bytes that may be pending to be written to a particular {@link Connection}.
     */
    void setMaxPendingBytesPerConnection(final int maxQueuedWrites);

    
Returns:
the maximum number of bytes that may be pending to be written to a particular Connection. By default, this will be four times the size of the Socket send buffer size./**
     * @return the maximum number of bytes that may be pending to be written to a particular {@link Connection}. By default,
     * this will be four times the size of the {@link java.net.Socket} send buffer size.
     */
    int getMaxPendingBytesPerConnection();

    
Returns true, if async write queue is allowed to write buffer directly during write(...) method call, w/o
adding buffer to the queue, or false otherwise.
Returns:
true, if async write queue is allowed to write buffer directly during write(...) method call, w/o
adding buffer to the queue, or false otherwise./**
     * Returns <tt>true</tt>, if async write queue is allowed to write buffer directly during write(...) method call, w/o
     * adding buffer to the queue, or <tt>false</tt> otherwise.
     *
     * @return <tt>true</tt>, if async write queue is allowed to write buffer directly during write(...) method call, w/o
     * adding buffer to the queue, or <tt>false</tt> otherwise.
     */
    boolean isAllowDirectWrite();

    
Set true, if async write queue is allowed to write buffer directly during write(...) method call, w/o adding
buffer to the queue, or false otherwise.
Params:
isAllowDirectWrite – true, if async write queue is allowed to write buffer directly during write(...)
method call, w/o adding buffer to the queue, or false otherwise./**
     * Set <tt>true</tt>, if async write queue is allowed to write buffer directly during write(...) method call, w/o adding
     * buffer to the queue, or <tt>false</tt> otherwise.
     *
     * @param isAllowDirectWrite <tt>true</tt>, if async write queue is allowed to write buffer directly during write(...)
     * method call, w/o adding buffer to the queue, or <tt>false</tt> otherwise.
     */
    void setAllowDirectWrite(final boolean isAllowDirectWrite);

}