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.HttpResponse; 034import org.apache.http.concurrent.Cancellable; 035import org.apache.http.nio.ContentDecoder; 036import org.apache.http.nio.IOControl; 037import org.apache.http.protocol.HttpContext; 038 039/** 040 * {@code HttpAsyncResponseConsumer} is a callback interface whose methods 041 * get invoked to process an HTTP response message and to stream message 042 * content from a non-blocking HTTP connection on the client side. 043 * 044 * @param <T> the result type of response processing. 045 * @since 4.2 046 */ 047public interface HttpAsyncResponseConsumer<T> extends Closeable, Cancellable { 048 049 /** 050 * Invoked when a HTTP response message is received. Please note 051 * that the {@link #consumeContent(ContentDecoder, IOControl)} method 052 * will be invoked only if the response messages has a content entity 053 * enclosed. 054 * 055 * @param response HTTP response message. 056 * @throws HttpException in case of HTTP protocol violation 057 * @throws IOException in case of an I/O error 058 */ 059 void responseReceived(HttpResponse response) throws IOException, HttpException; 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 response has been fully processed. 083 * 084 * @param context HTTP context 085 */ 086 void responseCompleted(HttpContext context); 087 088 /** 089 * Invoked to signal that the response 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 response processing 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 response processing, when available. This method 106 * returns {@code null} if the response processing is still ongoing. 107 * 108 * @see #isDone() 109 */ 110 T getResult(); 111 112 /** 113 * Determines whether or not the response processing completed. If the 114 * response processing terminated normally {@link #getResult()} 115 * can be used to obtain the result. If the response processing terminated 116 * abnormally {@link #getException()} can be used to obtain the cause. 117 */ 118 boolean isDone(); 119 120}