https://projects.eclipse.org/projects/ee4j.grizzly/grizzly-core: Grizzly Bill of Materials (BOM) (Oracle Corporation) 
/*
 * 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 org.glassfish.grizzly.asyncqueue.MessageCloner;
import org.glassfish.grizzly.asyncqueue.WritableMessage;


Implementations of this interface are able to write data from a Buffer to Connection. There are two basic Writer implementations in Grizzly: AsyncQueueWriter, TemporarySelectorWriter. 
Author:Alexey Stashok
Type parameters:
  • <L> – the writer address type
/**
 * Implementations of this interface are able to write data from a {@link Buffer}
 * to {@link Connection}.
 *
 * There are two basic Writer implementations in Grizzly:
 * {@link org.glassfish.grizzly.asyncqueue.AsyncQueueWriter},
 * {@link org.glassfish.grizzly.nio.tmpselectors.TemporarySelectorWriter}.
 *
 * @param <L> the writer address type
 * 
 * @author Alexey Stashok
 */
@SuppressWarnings("deprecation")
public interface Writer<L> {
    
Method writes the WritableMessage. 
Params:
Returns:Future, using which it's possible to check the result
/**
     * Method writes the {@link WritableMessage}.
     *
     *
     * @param connection the {@link org.glassfish.grizzly.Connection} to write to
     * @param message the {@link WritableMessage}, from which the data will be written
     * @return {@link Future}, using which it's possible to check the
     *         result
     */
    GrizzlyFuture<WriteResult<WritableMessage, L>> write(Connection<L> connection,
                                                         WritableMessage message) throws IOException;

    
Method writes the WritableMessage. 
Params:
/**
     * Method writes the {@link WritableMessage}.
     *
     *
     * @param connection the {@link org.glassfish.grizzly.Connection} to write 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
     */
    void write(Connection<L> connection,
               WritableMessage message,
               CompletionHandler<WriteResult<WritableMessage, L>> completionHandler);

    
Method writes the WritableMessage to the specific address. 
Params:
Returns:Future, using which it's possible to check the result
/**
     * Method writes the {@link WritableMessage} 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
     * @return {@link Future}, using which it's possible to check the
     *         result
     */
    GrizzlyFuture<WriteResult<WritableMessage, L>> write(Connection<L> connection,
                                                         L dstAddress, WritableMessage message);

    
Method writes the WritableMessage to the specific address. 
Params:
/**
     * Method writes the {@link WritableMessage} 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
     */
    void write(Connection<L> connection,
               L dstAddress, WritableMessage message,
               CompletionHandler<WriteResult<WritableMessage, L>> completionHandler);
    
    
Method writes the WritableMessage 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
Deprecated:push back logic is deprecated
/**
     * Method writes the {@link WritableMessage} 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 org.glassfish.grizzly.asyncqueue.PushBackHandler}, which will be notified
     *        if message was accepted by transport write queue or refused
     * @deprecated push back logic is deprecated
     */
    void write(
            Connection<L> connection,
            L dstAddress, WritableMessage message,
            CompletionHandler<WriteResult<WritableMessage, L>> completionHandler,
            org.glassfish.grizzly.asyncqueue.PushBackHandler pushBackHandler);

    
Method writes the WritableMessage 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
  • messageCloner – the MessageCloner, which will be able to clone the message in case it can't be completely written in the current thread.
/**
     * Method writes the {@link WritableMessage} 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 messageCloner the {@link MessageCloner}, which will be able to
     *          clone the message in case it can't be completely written in the
     *          current thread.
     */
    void write(
            Connection<L> connection,
            L dstAddress, WritableMessage message,
            CompletionHandler<WriteResult<WritableMessage, L>> completionHandler,
            MessageCloner<WritableMessage> messageCloner);

    
Return true if the connection has not exceeded it's maximum
 size in bytes of pending writes, otherwise false.

Params:
  • connection – the Connection to test whether or not the specified number of bytes can be written to.
Returns:true if the connection has not exceeded it's maximum
 size in bytes of pending writes, otherwise false
Since:2.3
/**
         * Return <code>true</code> if the connection has not exceeded it's maximum
         *  size in bytes of pending writes, otherwise <code>false</code>.
         *
         * @param connection the {@link Connection} to test whether or not the
         *  specified number of bytes can be written to.
         * @return <code>true</code> if the connection has not exceeded it's maximum
         *  size in bytes of pending writes, otherwise <code>false</code>
         *
         * @since 2.3
         */
        boolean canWrite(final Connection<L> connection);

        
Registers WriteHandler, which will be notified ones at least one byte can be written. This method call is equivalent to call notifyWritePossible(connection, writeHandler, 1); 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:
Since:2.3
/**
         * Registers {@link WriteHandler}, which will be notified ones at least one
         * byte can be written.
         *
         * This method call is equivalent to call notifyWritePossible(connection, writeHandler, <tt>1</tt>);
         *
         * 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.
         *
         * @since 2.3
         */
        void notifyWritePossible(final Connection<L> connection,
                final WriteHandler writeHandler);


    
Write reentrants counter

/**
     * Write reentrants counter
     */
    final class Reentrant {
        private static final ThreadLocal<Reentrant> REENTRANTS_COUNTER =
                new ThreadLocal<Reentrant>() {

                    @Override
                    protected Reentrant initialValue() {
                        return new Reentrant();
                    }
                };

        private static final int maxWriteReentrants = Integer.getInteger(
                "org.glassfish.grizzly.Writer.max-write-reentrants", 10);

        
Returns the maximum number of write() method reentrants a thread is
allowed to made. This is related to possible
write()->onComplete()->write()->... chain, which may grow infinitely
and cause StackOverflow. Using maxWriteReentrants value it's possible
to limit such a chain.

Returns:the maximum number of write() method reentrants a thread is
        allowed to make.
/**
         * Returns the maximum number of write() method reentrants a thread is
         * allowed to made. This is related to possible
         * write()->onComplete()->write()->... chain, which may grow infinitely
         * and cause StackOverflow. Using maxWriteReentrants value it's possible
         * to limit such a chain.
         *
         * @return the maximum number of write() method reentrants a thread is
         *         allowed to make.
         */
        public static int getMaxReentrants() {
            return maxWriteReentrants;
        }

        
Returns the current write reentrants counter. Might be useful, if developer wants to use custom notification mechanism, based on on Writer.canWrite(Connection<L>) and various write methods. 
/**
         * Returns the current write reentrants counter. Might be useful, if
         * developer wants to use custom notification mechanism, based on on {@link #canWrite(org.glassfish.grizzly.Connection)}
         * and various write methods.
         */
        public static Reentrant getWriteReentrant() {
            // ThreadLocal otherwise
            return REENTRANTS_COUNTER.get();
        }

        private int counter;

        
Returns the value of the reentrants counter for the current thread.

/**
         * Returns the value of the reentrants counter for the current thread.
         */
        public int get() {
            return counter;
        }

        
Increments the reentrants counter by one.

Returns:true if the counter (after incrementing) didn't reach getMaxReentrants() limit, or false otherwise.
/**
         * Increments the reentrants counter by one.
         *
         * @return <tt>true</tt> if the counter (after incrementing) didn't reach
         *         {@link #getMaxReentrants()} limit, or <tt>false</tt> otherwise.
         */
        public boolean inc() {
            return ++counter <= maxWriteReentrants;
        }

        
Decrements the reentrants counter by one.

Returns:true if the counter (after decrementing) didn't reach getMaxReentrants() limit, or false otherwise.
/**
         * Decrements the reentrants counter by one.
         *
         * @return <tt>true</tt> if the counter (after decrementing) didn't reach
         *         {@link #getMaxReentrants()} limit, or <tt>false</tt> otherwise.
         */
        public boolean dec() {
            return --counter <= maxWriteReentrants;
        }

        
Returns true, if max number of write->completion-handler reentrants has been reached for the passed Reentrant object, and next write will happen in the separate thread. 
Returns:true, if max number of write->completion-handler reentrants has been reached for the passed Reentrant object, and next write will happen in the separate thread.
/**
         * Returns <tt>true</tt>, if max number of write->completion-handler
         * reentrants has been reached for the passed {@link Reentrant} object,
         * and next write will happen in the separate thread.
         *
         * @return <tt>true</tt>, if max number of write->completion-handler
         *         reentrants has been reached for the passed {@link Reentrant} object,
         *         and next write will happen in the separate thread.
         */
        public boolean isMaxReentrantsReached() {
            return get() >= getMaxReentrants();
        }
    }
}