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 org.apache.http.HttpEntity;
31 import org.apache.http.HttpRequest;
32 import org.apache.http.HttpResponse;
33 import org.apache.http.concurrent.Cancellable;
34 import org.apache.http.nio.entity.HttpAsyncContentProducer;
35
36 /**
37 * <tt>HttpAsyncExchange</tt> represents a server-side HTTP message exchange
38 * where an HTTP response can be deferred without blocking the I/O event thread
39 * and triggered asynchronously at a later point of later time.
40 *
41 * @since 4.2
42 */
43 public interface HttpAsyncExchange {
44
45 /**
46 * Returns the received HTTP request message.
47 *
48 * @return received HTTP request message.
49 */
50 HttpRequest getRequest();
51
52 /**
53 * Returns the default HTTP response message. Once ready the response
54 * message can submitted using {@link #submitResponse()} method.
55 *
56 * @return default HTTP response message.
57 */
58 HttpResponse getResponse();
59
60 /**
61 * Submits the default HTTP response and completed the message exchange.
62 * If the response encloses an {@link HttpEntity} instance the entity is
63 * also expected to implement the {@link HttpAsyncContentProducer}
64 * interface for efficient content streaming to a non-blocking HTTP
65 * connection.
66 *
67 * @throws IllegalStateException if a response has already been submitted.
68 */
69 void submitResponse();
70
71 /**
72 * Submits an HTTP response using a custom
73 * {@link HttpAsyncResponseProducer}.
74 *
75 * @throws IllegalStateException if a response has already been submitted.
76 */
77 void submitResponse(HttpAsyncResponseProducer responseProducer);
78
79 /**
80 * Determines whether or not the message exchange has been completed.
81 *
82 * @return <code>true</code> if the message exchange has been completed,
83 * <code>false</code> otherwise.
84 */
85 boolean isCompleted();
86
87 /**
88 * Sets {@link Cancellable} callback to be invoked in case the underlying
89 * connection times out or gets terminated prematurely by the client. This
90 * callback can be used to cancel a long running response generating
91 * process if a response is no longer needed.
92 *
93 * @param cancellable
94 */
95 void setCallback(Cancellable cancellable);
96
97 /**
98 * Sets timeout for this message exchange.
99 */
100 void setTimeout(int timeout);
101
102 /**
103 * Returns timeout for this message exchange.
104 */
105 int getTimeout();
106
107 }