001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027package org.apache.http.nio.protocol;
028
029import java.io.Closeable;
030import java.io.IOException;
031
032import org.apache.http.HttpException;
033import org.apache.http.HttpRequest;
034import org.apache.http.nio.ContentDecoder;
035import org.apache.http.nio.IOControl;
036import org.apache.http.protocol.HttpContext;
037
038/**
039 * {@code HttpAsyncRequestConsumer} is a callback interface whose methods
040 * get invoked to process an HTTP request message and to stream message
041 * content from a non-blocking HTTP connection on the server side.
042 *
043 * @param <T> the result type of request processing.
044 * @since 4.2
045 */
046public interface HttpAsyncRequestConsumer<T> extends Closeable {
047
048    /**
049     * Invoked when a HTTP request message is received. Please note
050     * that the {@link #consumeContent(ContentDecoder, IOControl)} method
051     * will be invoked only for if the request message implements
052     * {@link org.apache.http.HttpEntityEnclosingRequest} interface and
053     * has a content entity enclosed.
054     *
055     * @param request HTTP request message.
056     * @throws HttpException in case of HTTP protocol violation
057     * @throws IOException in case of an I/O error
058     */
059    void requestReceived(HttpRequest request) throws HttpException, IOException;
060
061    /**
062     * Invoked to process a chunk of content from the {@link ContentDecoder}.
063     * The {@link IOControl} interface can be used to suspend input event
064     * notifications if the consumer is temporarily unable to process content.
065     * <p>
066     * The consumer can use the {@link ContentDecoder#isCompleted()} method
067     * to find out whether or not the message content has been fully consumed.
068     * <p>
069     * Please note that the {@link ContentDecoder} object is not thread-safe and
070     * should only be used within the context of this method call.
071     * The {@link IOControl} object can be shared and used on other thread
072     * to resume input event notifications when the consumer is capable of
073     * processing more content.
074     *
075     * @param decoder content decoder.
076     * @param ioctrl I/O control of the underlying connection.
077     * @throws IOException in case of an I/O error
078     */
079    void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
080
081    /**
082     * Invoked to signal that the request has been fully processed.
083     *
084     * @param context HTTP context
085     */
086    void requestCompleted(HttpContext context);
087
088    /**
089     * Invoked to signal that the request processing terminated abnormally.
090     *
091     * @param ex exception
092     */
093    void failed(Exception ex);
094
095    /**
096     * Returns an exception in case of an abnormal termination. This method
097     * returns {@code null} if the request execution is still ongoing
098     * or if it completed successfully.
099     *
100     * @see #isDone()
101     */
102    Exception getException();
103
104    /**
105     * Returns a result of the request execution, when available. This method
106     * returns {@code null} if the request execution is still ongoing.
107     *
108     * @see #isDone()
109     */
110    T getResult();
111
112    /**
113     * Determines whether or not the request execution completed. If the
114     * request processing terminated normally {@link #getResult()}
115     * can be used to obtain the result. If the request processing terminated
116     * abnormally {@link #getException()} can be used to obtain the cause.
117     */
118    boolean isDone();
119
120}