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
22 import org.apache.hadoop.hbase.classification.InterfaceAudience;
23 import org.apache.hadoop.hbase.classification.InterfaceStability;
24
25 /**
26 * <p>
27 * Extends {@link ByteRange} with additional methods to support tracking a
28 * consumers position within the viewport. The API is extended with methods
29 * {@link #get()} and {@link #put(byte)} for interacting with the backing
30 * array from the current position forward. This frees the caller from managing
31 * their own index into the array.
32 * </p>
33 * <p>
34 * Designed to be a slimmed-down, mutable alternative to {@link java.nio.ByteBuffer}.
35 * </p>
36 */
37 @InterfaceAudience.Public
38 @InterfaceStability.Evolving
39 public interface PositionedByteRange extends ByteRange {
40
41 // net new API is here.
42
43 /**
44 * The current {@code position} marker. This valuae is 0-indexed, relative to
45 * the beginning of the range.
46 */
47 public int getPosition();
48
49 /**
50 * Update the {@code position} index. May not be greater than {@code length}.
51 * @param position the new position in this range.
52 * @return this.
53 */
54 public PositionedByteRange setPosition(int position);
55
56 /**
57 * The number of bytes remaining between position and the end of the range.
58 */
59 public int getRemaining();
60
61 /**
62 * Retrieve the next byte from this range without incrementing position.
63 */
64 public byte peek();
65
66 /**
67 * Retrieve the next byte from this range.
68 */
69 public byte get();
70
71 /**
72 * Retrieve the next short value from this range.
73 */
74 public short getShort();
75
76 /**
77 * Retrieve the next int value from this range.
78 */
79 public int getInt();
80
81 /**
82 * Retrieve the next long value from this range.
83 */
84 public long getLong();
85
86 /**
87 * Retrieve the next long value, which is stored as VLong, from this range
88 * @return the long value which is stored as VLong
89 */
90 public long getVLong();
91
92 /**
93 * Fill {@code dst} with bytes from the range, starting from {@code position}.
94 * This range's {@code position} is incremented by the length of {@code dst},
95 * the number of bytes copied.
96 * @param dst the destination of the copy.
97 * @return this.
98 */
99 public PositionedByteRange get(byte[] dst);
100
101 /**
102 * Fill {@code dst} with bytes from the range, starting from the current
103 * {@code position}. {@code length} bytes are copied into {@code dst},
104 * starting at {@code offset}. This range's {@code position} is incremented
105 * by the number of bytes copied.
106 * @param dst the destination of the copy.
107 * @param offset the offset into {@code dst} to start the copy.
108 * @param length the number of bytes to copy into {@code dst}.
109 * @return this.
110 */
111 public PositionedByteRange get(byte[] dst, int offset, int length);
112
113 /**
114 * Store {@code val} at the next position in this range.
115 * @param val the new value.
116 * @return this.
117 */
118 public PositionedByteRange put(byte val);
119
120 /**
121 * Store short {@code val} at the next position in this range.
122 * @param val the new value.
123 * @return this.
124 */
125 public PositionedByteRange putShort(short val);
126
127 /**
128 * Store int {@code val} at the next position in this range.
129 * @param val the new value.
130 * @return this.
131 */
132 public PositionedByteRange putInt(int val);
133
134 /**
135 * Store long {@code val} at the next position in this range.
136 * @param val the new value.
137 * @return this.
138 */
139 public PositionedByteRange putLong(long val);
140
141 /**
142 * Store the long {@code val} at the next position as a VLong
143 * @param val the value to store
144 * @return number of bytes written
145 */
146 public int putVLong(long val);
147
148 /**
149 * Store the content of {@code val} in this range, starting at the next position.
150 * @param val the new value.
151 * @return this.
152 */
153 public PositionedByteRange put(byte[] val);
154
155 /**
156 * Store {@code length} bytes from {@code val} into this range. Bytes from
157 * {@code val} are copied starting at {@code offset} into the range, starting at
158 * the current position.
159 * @param val the new value.
160 * @param offset the offset in {@code val} from which to start copying.
161 * @param length the number of bytes to copy from {@code val}.
162 * @return this.
163 */
164 public PositionedByteRange put(byte[] val, int offset, int length);
165
166 /**
167 * Limits the byte range upto a specified value. Limit cannot be greater than
168 * capacity
169 *
170 * @param limit
171 * @return PositionedByteRange
172 */
173 public PositionedByteRange setLimit(int limit);
174
175 /**
176 * Return the current limit
177 *
178 * @return limit
179 */
180 public int getLimit();
181
182 // override parent interface declarations to return this interface.
183
184 @Override
185 public PositionedByteRange unset();
186
187 @Override
188 public PositionedByteRange set(int capacity);
189
190 @Override
191 public PositionedByteRange set(byte[] bytes);
192
193 @Override
194 public PositionedByteRange set(byte[] bytes, int offset, int length);
195
196 @Override
197 public PositionedByteRange setOffset(int offset);
198
199 @Override
200 public PositionedByteRange setLength(int length);
201
202 @Override
203 public PositionedByteRange get(int index, byte[] dst);
204
205 @Override
206 public PositionedByteRange get(int index, byte[] dst, int offset, int length);
207
208 @Override
209 public PositionedByteRange put(int index, byte val);
210
211 @Override
212 public PositionedByteRange putShort(int index, short val);
213
214 @Override
215 public PositionedByteRange putInt(int index, int val);
216
217 @Override
218 public PositionedByteRange putLong(int index, long val);
219
220 @Override
221 public PositionedByteRange put(int index, byte[] val);
222
223 @Override
224 public PositionedByteRange put(int index, byte[] val, int offset, int length);
225
226 @Override
227 public PositionedByteRange deepCopy();
228
229 @Override
230 public PositionedByteRange shallowCopy();
231
232 @Override
233 public PositionedByteRange shallowCopySubRange(int innerOffset, int copyLength);
234 }