1 /*

     2  * Copyright (c) 2017, 2018, 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.internal.net.http.websocket;

    27 

    28 import java.io.IOException;

    29 import java.nio.ByteBuffer;

    30 import java.util.concurrent.CompletableFuture;

    31 

    32 /*

    33  * Transport needs some way to asynchronously notify the send operation has been

    34  * completed. It can have several different designs each of which has its own

    35  * pros and cons:

    36  *

    37  *     (1) void sendMessage(..., Callback)

    38  *     (2) CompletableFuture<T> sendMessage(...)

    39  *     (3) CompletableFuture<T> sendMessage(..., Callback)

    40  *     (4) boolean sendMessage(..., Callback) throws IOException

    41  *     ...

    42  *

    43  * If Transport's users use CFs, (1) forces these users to create CFs and pass

    44  * them to the callback. If any additional (dependant) action needs to be

    45  * attached to the returned CF, this means an extra object (CF) must be created

    46  * in (2). (3) and (4) solves both issues, however (4) does not abstract out

    47  * when exactly the operation has been performed. So the handling code needs to

    48  * be repeated twice. And that leads to 2 different code paths (more bugs).

    49  * Unless designed for this, the user should not assume any specific order of

    50  * completion in (3) (e.g. callback first and then the returned CF).

    51  *

    52  * The only parametrization of Transport<T> used is Transport<WebSocket>. The

    53  * type parameter T was introduced solely to avoid circular dependency between

    54  * Transport and WebSocket. After all, instances of T are used solely to

    55  * complete CompletableFutures. Transport doesn't care about the exact type of

    56  * T.

    57  *

    58  * This way the Transport is fully in charge of creating CompletableFutures.

    59  * On the one hand, Transport may use it to cache/reuse CompletableFutures. On

    60  * the other hand, the class that uses Transport, may benefit by not converting

    61  * from CompletableFuture<K> returned from Transport, to CompletableFuture<V>

    62  * needed by the said class.

    63  */

    64 public interface Transport<T> {

    65 

    66     CompletableFuture<T> sendText(CharSequence message, boolean isLast);

    67 

    68     CompletableFuture<T> sendBinary(ByteBuffer message, boolean isLast);

    69 

    70     CompletableFuture<T> sendPing(ByteBuffer message);

    71 

    72     CompletableFuture<T> sendPong(ByteBuffer message);

    73 

    74     CompletableFuture<T> sendClose(int statusCode, String reason);

    75 

    76     void request(long n);

    77 

    78     /*

    79      * Why is this method needed? Since Receiver operates through callbacks

    80      * this method allows to abstract out what constitutes as a message being

    81      * received (i.e. to decide outside this type when exactly one should

    82      * decrement the demand).

    83      */

    84     void acknowledgeReception();

    85 

    86     void closeOutput() throws IOException;

    87 

    88     void closeInput() throws IOException;

    89 }