/*
 * Copyright (c) 2010, 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.InputStream;
import java.io.Reader;

 This interface defines methods to allow an InputStream or Reader to notify the developer when and how much
data is ready to be read without blocking.

Since:
2.0/**
 * <p>
 * This interface defines methods to allow an {@link InputStream} or
 * {@link Reader} to notify the developer <em>when</em> and <em>how much</em>
 * data is ready to be read without blocking.
 * </p>
 *
 * @since 2.0
 */
public interface InputSource {


    
 Notify the specified ReadHandler when any number of bytes or characters can be read without blocking. 

Invoking this method is equivalent to calling: notifyAvailable(handler, 1).

Params:
handler – the ReadHandler to notify.
Throws:
IllegalArgumentException – if handler is null.
IllegalStateException – if an attempt is made to register a handler
 before an existing registered handler has been invoked or if all request
 data has already been read.
See Also:
ReadHandler.onDataAvailable()
ReadHandler.onAllDataRead()/**
     * <p>
     * Notify the specified {@link ReadHandler} when any number of bytes or
     * characters can be read without blocking.
     * </p>
     *
     * <p>
     * Invoking this method is equivalent to calling: notifyAvailable(handler, 1).
     * </p>
     *
     * @param handler the {@link ReadHandler} to notify.
     *
     * @throws IllegalArgumentException if <code>handler</code> is <code>null</code>.
     * @throws IllegalStateException if an attempt is made to register a handler
     *  before an existing registered handler has been invoked or if all request
     *  data has already been read.
     *
     * @see ReadHandler#onDataAvailable()
     * @see ReadHandler#onAllDataRead()
     */
    void notifyAvailable(final ReadHandler handler);


    
 Notify the specified ReadHandler when the number of bytes that can be read without blocking is greater or equal to the specified size.

Params:
handler – the ReadHandler to notify.
size – the least number of bytes that must be available before the ReadHandler is invoked.
Throws:
IllegalArgumentException – if handler is null,
 or if size is less or equal to zero.
IllegalStateException – if an attempt is made to register a handler
 before an existing registered handler has been invoked or if all request
 data has already been read.
See Also:
ReadHandler.onDataAvailable()
ReadHandler.onAllDataRead()/**
     * <p>
     * Notify the specified {@link ReadHandler} when the number of bytes that
     * can be read without blocking is greater or equal to the specified
     * <code>size</code>.
     * </p>
     *
     * @param handler the {@link ReadHandler} to notify.
     * @param size the least number of bytes that must be available before
     *  the {@link ReadHandler} is invoked.
     *
     * @throws IllegalArgumentException if <code>handler</code> is <code>null</code>,
     *  or if <code>size</code> is less or equal to zero.
     * @throws IllegalStateException if an attempt is made to register a handler
     *  before an existing registered handler has been invoked or if all request
     *  data has already been read.
     *
     * @see ReadHandler#onDataAvailable()
     * @see ReadHandler#onAllDataRead()
     */
    void notifyAvailable(final ReadHandler handler, final int size);


    
Returns:
true when all data for this particular request
 has been read, otherwise returns false./**
     * @return <code>true</code> when all data for this particular request
     *  has been read, otherwise returns <code>false</code>.
     */
    boolean isFinished();


    
Returns:
the number of bytes (or characters) that may be obtained
 without blocking.  Note when dealing with characters, this method
 may return an estimate on the number of characters available./**
     * @return the number of bytes (or characters) that may be obtained
     *  without blocking.  Note when dealing with characters, this method
     *  may return an estimate on the number of characters available. 
     */
    int readyData();


    
Returns:
true if data can be obtained without blocking,
 otherwise returns false./**
     * @return <code>true</code> if data can be obtained without blocking,
     *  otherwise returns <code>false</code>.
     */
    boolean isReady();

}