1 /* 2 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package jdk.incubator.http; 27 28 import jdk.incubator.http.internal.common.ByteBufferReference; 29 30 import java.io.IOException; 31 import java.nio.ByteBuffer; 32 import java.util.function.Consumer; 33 import java.util.function.Supplier; 34 35 /** 36 * Implemented by classes that offer an asynchronous interface. 37 * 38 * PlainHttpConnection, AsyncSSLConnection AsyncSSLDelegate. 39 * 40 * setAsyncCallbacks() is called to set the callback for reading 41 * and error notification. Reads all happen on the selector thread, which 42 * must not block. 43 * 44 * Writing uses the same write() methods as used in blocking mode. 45 * Queues are employed on the writing side to buffer data while it is waiting 46 * to be sent. This strategy relies on HTTP/2 protocol flow control to stop 47 * outgoing queue from continually growing. Writes can be initiated by the 48 * calling thread, but if socket becomes full then the queue is emptied by 49 * the selector thread 50 */ 51 interface AsyncConnection { 52 53 /** 54 * Enables asynchronous sending and receiving mode. The given async 55 * receiver will receive all incoming data. asyncInput() will be called 56 * to trigger reads. asyncOutput() will be called to drive writes. 57 * 58 * The errorReceiver callback must be called when any fatal exception 59 * occurs. Connection is assumed to be closed afterwards. 60 */ 61 void setAsyncCallbacks(Consumer<ByteBufferReference> asyncReceiver, 62 Consumer<Throwable> errorReceiver, 63 Supplier<ByteBufferReference> readBufferSupplier); 64 65 66 67 /** 68 * Does whatever is required to start reading. Usually registers 69 * an event with the selector thread. 70 */ 71 void startReading(); 72 73 /** 74 * Cancel asynchronous reading. Used to downgrade a HTTP/2 connection to HTTP/1 75 */ 76 void stopAsyncReading(); 77 78 /** 79 * In async mode, this method puts buffers at the end of the send queue. 80 * When in async mode, calling this method should later be followed by 81 * subsequent flushAsync invocation. 82 * That allows multiple threads to put buffers into the queue while some other 83 * thread is writing. 84 */ 85 void writeAsync(ByteBufferReference[] buffers) throws IOException; 86 87 /** 88 * Re-enable asynchronous reads through the callback 89 */ 90 void enableCallback(); 91 92 /** 93 * In async mode, this method may put buffers at the beginning of send queue, 94 * breaking frames sequence and allowing to write these buffers before other 95 * buffers in the queue. 96 * When in async mode, calling this method should later be followed by 97 * subsequent flushAsync invocation. 98 * That allows multiple threads to put buffers into the queue while some other 99 * thread is writing. 100 */ 101 void writeAsyncUnordered(ByteBufferReference[] buffers) throws IOException; 102 103 /** 104 * This method should be called after any writeAsync/writeAsyncUnordered 105 * invocation. 106 * If there is a race to flushAsync from several threads one thread 107 * (race winner) capture flush operation and write the whole queue content. 108 * Other threads (race losers) exits from the method (not blocking) 109 * and continue execution. 110 */ 111 void flushAsync() throws IOException; 112 }