1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.http.nio.protocol;
29
30 import java.io.IOException;
31
32 import org.apache.http.HttpException;
33 import org.apache.http.HttpRequest;
34 import org.apache.http.protocol.HttpContext;
35
36 /**
37 * {@code HttpAsyncRequestHandler} represents a routine for asynchronous
38 * processing of a specific group of non-blocking HTTP requests. Protocol
39 * handlers are designed to take care of protocol specific aspects, whereas
40 * individual request handlers are expected to take care of application
41 * specific HTTP processing. The main purpose of a request handler is to
42 * generate a response object with a content entity to be sent back to
43 * the client in response to the given request.
44 *
45 * @since 4.2
46 */
47 public interface HttpAsyncRequestHandler<T> {
48
49 /**
50 * Triggered when an incoming request is received. This method should
51 * return a {@link HttpAsyncRequestConsumer} that will be used to process
52 * the request and consume message content if enclosed. The consumer
53 * can optionally parse or transform the message content into a structured
54 * object which is then passed onto
55 * the {@link #handle(Object, HttpAsyncExchange, HttpContext)}
56 * method for further processing.
57 *
58 * @param request the entity enclosing request.
59 * @param context the execution context.
60 * @return request consumer.
61 * @throws IOException in case of an I/O error.
62 * @throws HttpException in case of HTTP protocol violation or a processing
63 * problem.
64 */
65 HttpAsyncRequestConsumer<T> processRequest(
66 HttpRequest request,
67 HttpContext context) throws HttpException, IOException;
68
69 /**
70 * Triggered to complete request processing and to initiate the process of
71 * generating a response. This method does not have to submit a response
72 * immediately. It can defer transmission of an HTTP response back to
73 * the client without blocking the I/O thread by delegating the process
74 * of request handling to another service or a worker thread. HTTP response
75 * can be submitted as a later a later point of time using
76 * {@link HttpAsyncExchange} once response content becomes available.
77 *
78 * @param data request data returned by the request consumer.
79 * @param httpExchange HTTP exchange.
80 * @param context HTTP execution context.
81 * @throws IOException in case of an I/O error.
82 * @throws HttpException in case of HTTP protocol violation or a processing
83 * problem.
84 */
85 void handle(
86 T data,
87 HttpAsyncExchange httpExchange,
88 HttpContext context) throws HttpException, IOException;
89
90 }