001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.util;
019
020import org.apache.yetus.audience.InterfaceAudience;
021
022/**
023 * <p>
024 * Extends {@link ByteRange} with additional methods to support tracking a consumers position within
025 * the viewport. The API is extended with methods {@link #get()} and {@link #put(byte)} for
026 * interacting with the backing array from the current position forward. This frees the caller from
027 * managing their own index into the array.
028 * </p>
029 * <p>
030 * Designed to be a slimmed-down, mutable alternative to {@link java.nio.ByteBuffer}.
031 * </p>
032 */
033@InterfaceAudience.Public
034public interface PositionedByteRange extends ByteRange {
035
036  // net new API is here.
037
038  /**
039   * The current {@code position} marker. This valuae is 0-indexed, relative to the beginning of the
040   * range.
041   */
042  public int getPosition();
043
044  /**
045   * Update the {@code position} index. May not be greater than {@code length}.
046   * @param position the new position in this range.
047   * @return this.
048   */
049  public PositionedByteRange setPosition(int position);
050
051  /**
052   * The number of bytes remaining between position and the end of the range.
053   */
054  public int getRemaining();
055
056  /**
057   * Retrieve the next byte from this range without incrementing position.
058   */
059  public byte peek();
060
061  /**
062   * Retrieve the next byte from this range.
063   */
064  public byte get();
065
066  /**
067   * Retrieve the next short value from this range.
068   */
069  public short getShort();
070
071  /**
072   * Retrieve the next int value from this range.
073   */
074  public int getInt();
075
076  /**
077   * Retrieve the next long value from this range.
078   */
079  public long getLong();
080
081  /**
082   * Retrieve the next long value, which is stored as VLong, from this range
083   * @return the long value which is stored as VLong
084   */
085  public long getVLong();
086
087  /**
088   * Fill {@code dst} with bytes from the range, starting from {@code position}. This range's
089   * {@code position} is incremented by the length of {@code dst}, the number of bytes copied.
090   * @param dst the destination of the copy.
091   * @return this.
092   */
093  public PositionedByteRange get(byte[] dst);
094
095  /**
096   * Fill {@code dst} with bytes from the range, starting from the current {@code position}.
097   * {@code length} bytes are copied into {@code dst}, starting at {@code offset}. This range's
098   * {@code position} is incremented by the number of bytes copied.
099   * @param dst    the destination of the copy.
100   * @param offset the offset into {@code dst} to start the copy.
101   * @param length the number of bytes to copy into {@code dst}.
102   * @return this.
103   */
104  public PositionedByteRange get(byte[] dst, int offset, int length);
105
106  /**
107   * Store {@code val} at the next position in this range.
108   * @param val the new value.
109   * @return this.
110   */
111  public PositionedByteRange put(byte val);
112
113  /**
114   * Store short {@code val} at the next position in this range.
115   * @param val the new value.
116   * @return this.
117   */
118  public PositionedByteRange putShort(short val);
119
120  /**
121   * Store int {@code val} at the next position in this range.
122   * @param val the new value.
123   * @return this.
124   */
125  public PositionedByteRange putInt(int val);
126
127  /**
128   * Store long {@code val} at the next position in this range.
129   * @param val the new value.
130   * @return this.
131   */
132  public PositionedByteRange putLong(long val);
133
134  /**
135   * Store the long {@code val} at the next position as a VLong
136   * @param val the value to store
137   * @return number of bytes written
138   */
139  public int putVLong(long val);
140
141  /**
142   * Store the content of {@code val} in this range, starting at the next position.
143   * @param val the new value.
144   * @return this.
145   */
146  public PositionedByteRange put(byte[] val);
147
148  /**
149   * Store {@code length} bytes from {@code val} into this range. Bytes from {@code val} are copied
150   * starting at {@code offset} into the range, starting at the current position.
151   * @param val    the new value.
152   * @param offset the offset in {@code val} from which to start copying.
153   * @param length the number of bytes to copy from {@code val}.
154   * @return this.
155   */
156  public PositionedByteRange put(byte[] val, int offset, int length);
157
158  /**
159   * Limits the byte range upto a specified value. Limit cannot be greater than capacity nn
160   */
161  public PositionedByteRange setLimit(int limit);
162
163  /**
164   * Return the current limit n
165   */
166  public int getLimit();
167
168  // override parent interface declarations to return this interface.
169
170  @Override
171  public PositionedByteRange unset();
172
173  @Override
174  public PositionedByteRange set(int capacity);
175
176  @Override
177  public PositionedByteRange set(byte[] bytes);
178
179  @Override
180  public PositionedByteRange set(byte[] bytes, int offset, int length);
181
182  @Override
183  public PositionedByteRange setOffset(int offset);
184
185  @Override
186  public PositionedByteRange setLength(int length);
187
188  @Override
189  public PositionedByteRange get(int index, byte[] dst);
190
191  @Override
192  public PositionedByteRange get(int index, byte[] dst, int offset, int length);
193
194  @Override
195  public PositionedByteRange put(int index, byte val);
196
197  @Override
198  public PositionedByteRange putShort(int index, short val);
199
200  @Override
201  public PositionedByteRange putInt(int index, int val);
202
203  @Override
204  public PositionedByteRange putLong(int index, long val);
205
206  @Override
207  public PositionedByteRange put(int index, byte[] val);
208
209  @Override
210  public PositionedByteRange put(int index, byte[] val, int offset, int length);
211
212  @Override
213  public PositionedByteRange deepCopy();
214
215  @Override
216  public PositionedByteRange shallowCopy();
217
218  @Override
219  public PositionedByteRange shallowCopySubRange(int innerOffset, int copyLength);
220}