package org.eclipse.jetty.server;

import java.io.IOException;

import javax.servlet.http.Part;

/**
 * <p>
 * This class represents a call-back mechanism that will notify implementations
 * as HTTP multipart request data becomes available to be read without blocking.
 * </p>
 * <p>
 * A typical usage pattern is:
 * <pre>
 *    class MyPartListener implements PartListener
 *    {
 *      public void onPartAvailable(Stream stream) throws IOException
 *      {
 *        while(stream.isReady())
 *          process(stream.getPart());
 *      }
 *    }
 *  </pre>
 */
public interface PartListener
{
    /**
     * When an instance of the <code>PartListener</code> is registered with a {@link ServletInputStream},
     * this method will be invoked by the container the first time when it is possible
     * to read a part. Subsequently the container will invoke this method if and only
     * if {@link Stream#isReady()} method has been called and has returned <code>false</code>.
     *
     * @throws IOException if an I/O related error has occurred during processing
     */
    void onPartAvailable(PartListener.Stream stream) throws IOException;

    /**
     * Invoked when all data for the current request has been read.
     *
     * @throws IOException if an I/O related error has occurred during processing
     */

    public default void onAllDataRead() throws IOException {};

    /**
     * Invoked when an error occurs processing the request.
     */
    public default void onError(Throwable t) {};
    
    public interface Stream
    {
        /**
         * @return True if a Part is available to be returned from getPart();
         */
        boolean isReady();
        
        /**
         * @return A Part that has been read from the request body.  The part will be fully
         * constituted either in memory or as a file, so that any calls on the {@link Part#getInputStream()}
         * will not block on the remote connection.
         * @throws IllegalStateException if {@link #isReady()} has not been call or has been
         * called and returned false.
         */
        Part getPart();
    }
}