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 package org.apache.http.nio.protocol;
28
29 import java.io.Closeable;
30 import java.io.IOException;
31
32 import org.apache.http.HttpEntityEnclosingRequest;
33 import org.apache.http.HttpException;
34 import org.apache.http.HttpRequest;
35 import org.apache.http.nio.ContentDecoder;
36 import org.apache.http.nio.IOControl;
37 import org.apache.http.protocol.HttpContext;
38
39 /**
40 * <tt>HttpAsyncRequestConsumer</tt> is a callback interface whose methods
41 * get invoked to process an HTTP request message and to stream message
42 * content from a non-blocking HTTP connection on the server side.
43 *
44 * @param <T> the result type of request processing.
45 * @since 4.2
46 */
47 public interface HttpAsyncRequestConsumer<T> extends Closeable {
48
49 /**
50 * Invoked when a HTTP request message is received. Please note
51 * that the {@link #consumeContent(ContentDecoder, IOControl)} method
52 * will be invoked only for if the request message implements
53 * {@link HttpEntityEnclosingRequest} interface and has a content
54 * entity enclosed.
55 *
56 * @param request HTTP request message.
57 * @throws HttpException in case of HTTP protocol violation
58 * @throws IOException in case of an I/O error
59 */
60 void requestReceived(HttpRequest request) throws HttpException, IOException;
61
62 /**
63 * Invoked to process a chunk of content from the {@link ContentDecoder}.
64 * The {@link IOControl} interface can be used to suspend input event
65 * notifications if the consumer is temporarily unable to process content.
66 * <p/>
67 * The consumer can use the {@link ContentDecoder#isCompleted()} method
68 * to find out whether or not the message content has been fully consumed.
69 * <p/>
70 * Please note that the {@link ContentDecoder} object is not thread-safe and
71 * should only be used within the context of this method call.
72 * The {@link IOControl} object can be shared and used on other thread
73 * to resume input event notifications when the consumer is capable of
74 * processing more content.
75 *
76 * @param decoder content decoder.
77 * @param ioctrl I/O control of the underlying connection.
78 * @throws IOException in case of an I/O error
79 */
80 void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
81
82 /**
83 * Invoked to signal that the request has been fully processed.
84 *
85 * @param context HTTP context
86 */
87 void requestCompleted(HttpContext context);
88
89 /**
90 * Invoked to signal that the request processing terminated abnormally.
91 *
92 * @param ex exception
93 */
94 void failed(Exception ex);
95
96 /**
97 * Returns an exception in case of an abnormal termination. This method
98 * returns <code>null</code> if the request execution is still ongoing
99 * or if it completed successfully.
100 *
101 * @see #isDone()
102 */
103 Exception getException();
104
105 /**
106 * Returns a result of the request execution, when available. This method
107 * returns <code>null</code> if the request execution is still ongoing.
108 *
109 * @see #isDone()
110 */
111 T getResult();
112
113 /**
114 * Determines whether or not the request execution completed. If the
115 * request processing terminated normally {@link #getResult()}
116 * can be used to obtain the result. If the request processing terminated
117 * abnormally {@link #getException()} can be used to obtain the cause.
118 */
119 boolean isDone();
120
121 }