/*******************************************************************************
* Copyright (c)                                                                *
*           2005   Tristan Allwood,                                            *
*           2005   Daniel Burke,                                               *
*           2005   Marc Hull,                                                  *
*           2005   Ekaterina Itskova,                                          *
*           2005   Steve Zymler                                                *
*                                                                              *
* Permission is hereby granted, free of charge, to any person obtaining a      *
* copy of this software and associated documentation files (the                *
* "Software"), to deal in the Software without restriction, including          *
* without limitation the rights to use, copy, modify, merge, publish,          *
* distribute, sublicense, and/or sell copies of the Software, and to           *
* permit persons to whom the Software is furnished to do so, subject to        *
* the following conditions:                                                    *
*                                                                              *
* The above copyright notice and this permission notice shall be included      *
* in all copies or substantial portions of the Software.                       *
*                                                                              *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS      *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                   *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.       *
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY         *
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,         *
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE            *
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                       *
*******************************************************************************/
package uk.ac.ic.doc.kevlar.publicInterfaces;


/**
 * @author tora
 */
public interface IInputPipe extends IPipeEnd {

    /**
     * Reads from the pipe
     * 
     * @return an object from the pipe. If there is no object available, it
     *         blocks waiting for the next one.  This method could block and
     *         then throw IllegalStateException
     * @throws IllegalStateException
     *             if there is nothing to read and the pipe has been closed.
     * @throws InterruptedException
     *             if the thread is interrupted while waiting to read from the
     *             pipe.
     */
    IType read() throws InterruptedException;

    /**
     * @return true iff the next call to read will not block. This method
     * 				returns immediately
     * @throws IllegalStateException
     *             if there is nothing to read and the pipe has been closed
     *             at this time ( this does not guarantee a subsiquent read()
     *             will not be closed however ).
     */
    boolean ready();
    
    /**
     * Add an event listener that is notified whenever this IInputPipe
     * moves into a state where ready will return true.
     * Be warned, the events coming back are in the PipeManager thread
     * and hold locks. You are <b>Strongly advised</b> not to make any calls
     * here that could take time to run, or require locks or call methods in
     * other IInput or IOutput pipes.
     * @param irel
     */
    void addReadyEventListener(IReadyEventListener irel);
    
}
