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