1 /*
2 * Copyright 2021 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://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, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.buffer.api;
17
18 import java.nio.ByteBuffer;
19
20 /**
21 * A view onto the buffer component being processed in a given iteration of
22 * {@link Buffer#forEachWritable(int, WritableComponentProcessor)}.
23 */
24 public interface WritableComponent {
25
26 /**
27 * Check if this component is backed by a cached byte array that can be accessed cheaply.
28 *
29 * @return {@code true} if {@link #writableArray()} is a cheap operation, otherwise {@code false}.
30 */
31 boolean hasWritableArray();
32
33 /**
34 * Get a byte array of the contents of this component.
35 *
36 * @return A byte array of the contents of this component.
37 * @throws UnsupportedOperationException if {@link #hasWritableArray()} returns {@code false}.
38 * @see #writableArrayOffset()
39 * @see #writableArrayLength()
40 */
41 byte[] writableArray();
42
43 /**
44 * An offset into the {@link #writableArray()} where this component starts.
45 *
46 * @return An offset into {@link #writableArray()}.
47 * @throws UnsupportedOperationException if {@link #hasWritableArray()} returns {@code false}.
48 */
49 int writableArrayOffset();
50
51 /**
52 * The number of bytes in the {@link #writableArray()} that belong to this component.
53 *
54 * @return The number of bytes, from the {@link #writableArrayOffset()} into the {@link #writableArray()},
55 * that belong to this component.
56 * @throws UnsupportedOperationException if {@link #hasWritableArray()} returns {@code false}.
57 */
58 int writableArrayLength();
59
60 /**
61 * Give the native memory address backing this buffer, or return 0 if this buffer has no native memory address.
62 *
63 * @return The native memory address, if any, otherwise 0.
64 */
65 long writableNativeAddress();
66
67 /**
68 * Get the space available to be written to this component, as a number of bytes.
69 *
70 * @return The maximum number of bytes that can be written to this component.
71 */
72 int writableBytes();
73
74 /**
75 * Get a {@link ByteBuffer} instance for this memory component, which can be used for modifying the buffer
76 * contents.
77 *
78 * @return A new {@link ByteBuffer}, with its own position and limit, for this memory component.
79 */
80 ByteBuffer writableBuffer();
81
82 /**
83 * Move the write-offset to indicate that the given number of bytes were written to this component.
84 *
85 * @param byteCount The number of bytes written to this component.
86 * @return itself.
87 * @see Buffer#skipWritableBytes(int)
88 */
89 WritableComponent skipWritableBytes(int byteCount);
90 }