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 */
027
028package org.apache.http.nio.protocol;
029
030import java.io.IOException;
031
032import org.apache.http.HttpException;
033import org.apache.http.HttpRequest;
034import org.apache.http.protocol.HttpContext;
035
036/**
037 * {@code HttpAsyncRequestHandler} represents a routine for asynchronous
038 * processing of a specific group of non-blocking HTTP requests. Protocol
039 * handlers are designed to take care of protocol specific aspects, whereas
040 * individual request handlers are expected to take care of application
041 * specific HTTP processing. The main purpose of a request handler is to
042 * generate a response object with a content entity to be sent back to
043 * the client in response to the given request.
044 *
045 * @since 4.2
046 */
047public interface HttpAsyncRequestHandler<T> {
048
049    /**
050     * Triggered when an incoming request is received. This method should
051     * return a {@link HttpAsyncRequestConsumer} that will be used to process
052     * the request and consume message content if enclosed. The consumer
053     * can optionally parse or transform the message content into a structured
054     * object which is then passed onto
055     * the {@link #handle(Object, HttpAsyncExchange, HttpContext)}
056     * method for further processing.
057     *
058     * @param request the entity enclosing request.
059     * @param context the execution context.
060     * @return request consumer.
061     * @throws IOException in case of an I/O error.
062     * @throws HttpException in case of HTTP protocol violation or a processing
063     *   problem.
064     */
065    HttpAsyncRequestConsumer<T> processRequest(
066            HttpRequest request,
067            HttpContext context) throws HttpException, IOException;
068
069    /**
070     * Triggered to complete request processing and to initiate the process of
071     * generating a response. This method does not have to submit a response
072     * immediately. It can defer transmission of an HTTP response back to
073     * the client without blocking the I/O thread by delegating the process
074     * of request handling to another service or a worker thread. HTTP response
075     * can be submitted as a later a later point of time using
076     * {@link HttpAsyncExchange} once response content becomes available.
077     *
078     * @param data request data returned by the request consumer.
079     * @param httpExchange HTTP exchange.
080     * @param context HTTP execution context.
081     * @throws IOException in case of an I/O error.
082     * @throws HttpException in case of HTTP protocol violation or a processing
083     *   problem.
084     */
085    void handle(
086            T data,
087            HttpAsyncExchange httpExchange,
088            HttpContext context) throws HttpException, IOException;
089
090}