1 /* 2 * Copyright (C) 2014 Square, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.squareup.okhttp.internal.framed; 17 18 import java.io.IOException; 19 import java.util.List; 20 import okio.BufferedSource; 21 22 /** 23 * {@link com.squareup.okhttp.Protocol#HTTP_2 HTTP/2} only. 24 * Processes server-initiated HTTP requests on the client. Implementations must 25 * quickly dispatch callbacks to avoid creating a bottleneck. 26 * 27 * <p>While {@link #onReset} may occur at any time, the following callbacks are 28 * expected in order, correlated by stream ID. 29 * <ul> 30 * <li>{@link #onRequest}</li> 31 * <li>{@link #onHeaders} (unless canceled)</li> 32 * <li>{@link #onData} (optional sequence of data frames)</li> 33 * </ul> 34 * 35 * <p>As a stream ID is scoped to a single HTTP/2 connection, implementations 36 * which target multiple connections should expect repetition of stream IDs. 37 * 38 * <p>Return true to request cancellation of a pushed stream. Note that this 39 * does not guarantee future frames won't arrive on the stream ID. 40 */ 41 public interface PushObserver { 42 /** 43 * Describes the request that the server intends to push a response for. 44 * 45 * @param streamId server-initiated stream ID: an even number. 46 * @param requestHeaders minimally includes {@code :method}, {@code :scheme}, 47 * {@code :authority}, and (@code :path}. 48 */ onRequest(int streamId, List<Header> requestHeaders)49 boolean onRequest(int streamId, List<Header> requestHeaders); 50 51 /** 52 * The response headers corresponding to a pushed request. When {@code last} 53 * is true, there are no data frames to follow. 54 * 55 * @param streamId server-initiated stream ID: an even number. 56 * @param responseHeaders minimally includes {@code :status}. 57 * @param last when true, there is no response data. 58 */ onHeaders(int streamId, List<Header> responseHeaders, boolean last)59 boolean onHeaders(int streamId, List<Header> responseHeaders, boolean last); 60 61 /** 62 * A chunk of response data corresponding to a pushed request. This data 63 * must either be read or skipped. 64 * 65 * @param streamId server-initiated stream ID: an even number. 66 * @param source location of data corresponding with this stream ID. 67 * @param byteCount number of bytes to read or skip from the source. 68 * @param last when true, there are no data frames to follow. 69 */ onData(int streamId, BufferedSource source, int byteCount, boolean last)70 boolean onData(int streamId, BufferedSource source, int byteCount, boolean last) 71 throws IOException; 72 73 /** Indicates the reason why this stream was canceled. */ onReset(int streamId, ErrorCode errorCode)74 void onReset(int streamId, ErrorCode errorCode); 75 76 PushObserver CANCEL = new PushObserver() { 77 78 @Override public boolean onRequest(int streamId, List<Header> requestHeaders) { 79 return true; 80 } 81 82 @Override public boolean onHeaders(int streamId, List<Header> responseHeaders, boolean last) { 83 return true; 84 } 85 86 @Override public boolean onData(int streamId, BufferedSource source, int byteCount, 87 boolean last) throws IOException { 88 source.skip(byteCount); 89 return true; 90 } 91 92 @Override public void onReset(int streamId, ErrorCode errorCode) { 93 } 94 }; 95 } 96