1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.apache.hadoop.hbase.util;
20
21 import java.nio.ByteBuffer;
22
23 import org.apache.hadoop.classification.InterfaceAudience;
24 import org.apache.hadoop.classification.InterfaceStability;
25
26 /**
27 * <p>
28 * Extends {@link ByteRange} with additional methods to support tracking a
29 * consumers position within the viewport. The API is extended with methods
30 * {@link #get()} and {@link #put(byte)} for interacting with the backing
31 * array from the current position forward. This frees the caller from managing
32 * their own index into the array.
33 * </p>
34 * <p>
35 * Designed to be a slimmed-down, mutable alternative to {@link ByteBuffer}.
36 * </p>
37 */
38 @InterfaceAudience.Public
39 @InterfaceStability.Evolving
40 public interface PositionedByteRange extends ByteRange {
41
42 // net new API is here.
43
44 /**
45 * The current {@code position} marker. This valuae is 0-indexed, relative to
46 * the beginning of the range.
47 */
48 public int getPosition();
49
50 /**
51 * Update the {@code position} index. May not be greater than {@code length}.
52 * @param position the new position in this range.
53 * @return this.
54 */
55 public PositionedByteRange setPosition(int position);
56
57 /**
58 * The number of bytes remaining between position and the end of the range.
59 */
60 public int getRemaining();
61
62 /**
63 * Retrieve the next byte from this range without incrementing position.
64 */
65 public byte peek();
66
67 /**
68 * Retrieve the next byte from this range.
69 */
70 public byte get();
71
72 /**
73 * Fill {@code dst} with bytes from the range, starting from {@code position}.
74 * This range's {@code position} is incremented by the length of {@code dst},
75 * the number of bytes copied.
76 * @param dst the destination of the copy.
77 * @return this.
78 */
79 public PositionedByteRange get(byte[] dst);
80
81 /**
82 * Fill {@code dst} with bytes from the range, starting from the current
83 * {@code position}. {@code length} bytes are copied into {@code dst},
84 * starting at {@code offset}. This range's {@code position} is incremented
85 * by the number of bytes copied.
86 * @param dst the destination of the copy.
87 * @param offset the offset into {@code dst} to start the copy.
88 * @param length the number of bytes to copy into {@code dst}.
89 * @return this.
90 */
91 public PositionedByteRange get(byte[] dst, int offset, int length);
92
93 /**
94 * Store {@code val} at the next position in this range.
95 * @param val the new value.
96 * @return this.
97 */
98 public PositionedByteRange put(byte val);
99
100 /**
101 * Store the content of {@code val} in this range, starting at the next position.
102 * @param val the new value.
103 * @return this.
104 */
105 public PositionedByteRange put(byte[] val);
106
107 /**
108 * Store {@code length} bytes from {@code val} into this range. Bytes from
109 * {@code val} are copied starting at {@code offset} into the range, starting at
110 * the current position.
111 * @param val the new value.
112 * @param offset the offset in {@code val} from which to start copying.
113 * @param length the number of bytes to copy from {@code val}.
114 * @return this.
115 */
116 public PositionedByteRange put(byte[] val, int offset, int length);
117
118 // override parent interface declarations to return this interface.
119
120 @Override
121 public PositionedByteRange unset();
122
123 @Override
124 public PositionedByteRange set(int capacity);
125
126 @Override
127 public PositionedByteRange set(byte[] bytes);
128
129 @Override
130 public PositionedByteRange set(byte[] bytes, int offset, int length);
131
132 @Override
133 public PositionedByteRange setOffset(int offset);
134
135 @Override
136 public PositionedByteRange setLength(int length);
137
138 @Override
139 public PositionedByteRange get(int index, byte[] dst);
140
141 @Override
142 public PositionedByteRange get(int index, byte[] dst, int offset, int length);
143
144 @Override
145 public PositionedByteRange put(int index, byte val);
146
147 @Override
148 public PositionedByteRange put(int index, byte[] val);
149
150 @Override
151 public PositionedByteRange put(int index, byte[] val, int offset, int length);
152
153 @Override
154 public PositionedByteRange deepCopy();
155
156 @Override
157 public PositionedByteRange shallowCopy();
158
159 @Override
160 public PositionedByteRange shallowCopySubRange(int innerOffset, int copyLength);
161 }