1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.hc.core5.http.nio;
29
30 import java.io.IOException;
31 import java.nio.ByteBuffer;
32 import java.util.List;
33
34 import org.apache.hc.core5.annotation.Contract;
35 import org.apache.hc.core5.annotation.ThreadingBehavior;
36 import org.apache.hc.core5.http.Header;
37
38 /**
39 * Abstract byte stream channel
40 * <p>
41 * Implementations are expected to be thread-safe.
42 * </p>
43 *
44 * @since 5.0
45 */
46 @Contract(threading = ThreadingBehavior.SAFE)
47 public interface DataStreamChannel extends StreamChannel<ByteBuffer> {
48
49 /**
50 * Signals intent by the data producer to produce more data.
51 * Once the channel is able to accept data its handler is expected
52 * to trigger an event to notify the data producer.
53 */
54 void requestOutput();
55
56 /**
57 * Writes data from the buffer through this channel into the underlying byte stream.
58 * If the underlying byte stream is temporarily unable to accept more data
59 * it can return zero to indicate that no data could be written to the data
60 * stream. The data producer can choose to call {@link #requestOutput()}
61 * to signal its intent to produce more data.
62 *
63 * @param src source of data
64 *
65 * @return The number of bytes written, possibly zero
66 */
67 @Override
68 int write(ByteBuffer src) throws IOException;
69
70 /**
71 * Terminates the underlying data stream and optionally writes
72 * a closing sequence with the given trailers.
73 * <p>
74 * Please note that some data streams may not support trailers
75 * and may silently ignore the trailers parameter.
76 * </p>
77 */
78 void endStream(List<? extends Header> trailers) throws IOException;
79
80 }