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 */ 027package org.apache.http.nio.protocol; 028 029import java.io.Closeable; 030import java.io.IOException; 031 032import org.apache.http.HttpException; 033import org.apache.http.HttpRequest; 034import org.apache.http.nio.ContentDecoder; 035import org.apache.http.nio.IOControl; 036import org.apache.http.protocol.HttpContext; 037 038/** 039 * {@code HttpAsyncRequestConsumer} is a callback interface whose methods 040 * get invoked to process an HTTP request message and to stream message 041 * content from a non-blocking HTTP connection on the server side. 042 * 043 * @param <T> the result type of request processing. 044 * @since 4.2 045 */ 046public interface HttpAsyncRequestConsumer<T> extends Closeable { 047 048 /** 049 * Invoked when a HTTP request message is received. Please note 050 * that the {@link #consumeContent(ContentDecoder, IOControl)} method 051 * will be invoked only for if the request message implements 052 * {@link org.apache.http.HttpEntityEnclosingRequest} interface and 053 * has a content entity enclosed. 054 * 055 * @param request HTTP request message. 056 * @throws HttpException in case of HTTP protocol violation 057 * @throws IOException in case of an I/O error 058 */ 059 void requestReceived(HttpRequest request) throws HttpException, IOException; 060 061 /** 062 * Invoked to process a chunk of content from the {@link ContentDecoder}. 063 * The {@link IOControl} interface can be used to suspend input event 064 * notifications if the consumer is temporarily unable to process content. 065 * <p> 066 * The consumer can use the {@link ContentDecoder#isCompleted()} method 067 * to find out whether or not the message content has been fully consumed. 068 * <p> 069 * Please note that the {@link ContentDecoder} object is not thread-safe and 070 * should only be used within the context of this method call. 071 * The {@link IOControl} object can be shared and used on other thread 072 * to resume input event notifications when the consumer is capable of 073 * processing more content. 074 * 075 * @param decoder content decoder. 076 * @param ioctrl I/O control of the underlying connection. 077 * @throws IOException in case of an I/O error 078 */ 079 void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException; 080 081 /** 082 * Invoked to signal that the request has been fully processed. 083 * 084 * @param context HTTP context 085 */ 086 void requestCompleted(HttpContext context); 087 088 /** 089 * Invoked to signal that the request processing terminated abnormally. 090 * 091 * @param ex exception 092 */ 093 void failed(Exception ex); 094 095 /** 096 * Returns an exception in case of an abnormal termination. This method 097 * returns {@code null} if the request execution is still ongoing 098 * or if it completed successfully. 099 * 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}