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 */
018
019package org.apache.hadoop.hbase.util;
020
021
022import org.apache.yetus.audience.InterfaceAudience;
023
024/**
025 * <p>
026 * Extends {@link ByteRange} with additional methods to support tracking a
027 * consumers position within the viewport. The API is extended with methods
028 * {@link #get()} and {@link #put(byte)} for interacting with the backing
029 * array from the current position forward. This frees the caller from managing
030 * their own index into the array.
031 * </p>
032 * <p>
033 * Designed to be a slimmed-down, mutable alternative to {@link java.nio.ByteBuffer}.
034 * </p>
035 */
036@InterfaceAudience.Public
037public interface PositionedByteRange extends ByteRange {
038
039  // net new API is here.
040
041  /**
042   * The current {@code position} marker. This valuae is 0-indexed, relative to
043   * the beginning of the range.
044   */
045  public int getPosition();
046
047  /**
048   * Update the {@code position} index. May not be greater than {@code length}.
049   * @param position the new position in this range.
050   * @return this.
051   */
052  public PositionedByteRange setPosition(int position);
053
054  /**
055   * The number of bytes remaining between position and the end of the range.
056   */
057  public int getRemaining();
058
059  /**
060   * Retrieve the next byte from this range without incrementing position.
061   */
062  public byte peek();
063
064  /**
065   * Retrieve the next byte from this range.
066   */
067  public byte get();
068
069  /**
070   * Retrieve the next short value from this range.
071   */
072  public short getShort();
073
074  /**
075   * Retrieve the next int value from this range.
076   */
077  public int getInt();
078
079  /**
080   * Retrieve the next long value from this range.
081   */
082  public long getLong();
083
084  /**
085   * Retrieve the next long value, which is stored as VLong, from this range
086   * @return the long value which is stored as VLong
087   */
088  public long getVLong();
089
090  /**
091   * Fill {@code dst} with bytes from the range, starting from {@code position}.
092   * This range's {@code position} is incremented by the length of {@code dst},
093   * the number of bytes copied.
094   * @param dst the destination of the copy.
095   * @return this.
096   */
097  public PositionedByteRange get(byte[] dst);
098
099  /**
100   * Fill {@code dst} with bytes from the range, starting from the current
101   * {@code position}. {@code length} bytes are copied into {@code dst},
102   * starting at {@code offset}. This range's {@code position} is incremented
103   * by the number of bytes copied.
104   * @param dst the destination of the copy.
105   * @param offset the offset into {@code dst} to start the copy.
106   * @param length the number of bytes to copy into {@code dst}.
107   * @return this.
108   */
109  public PositionedByteRange get(byte[] dst, int offset, int length);
110
111  /**
112   * Store {@code val} at the next position in this range.
113   * @param val the new value.
114   * @return this.
115   */
116  public PositionedByteRange put(byte val);
117
118  /**
119   * Store short {@code val} at the next position in this range.
120   * @param val the new value.
121   * @return this.
122   */
123  public PositionedByteRange putShort(short val);
124
125  /**
126   * Store int {@code val} at the next position in this range.
127   * @param val the new value.
128   * @return this.
129   */
130  public PositionedByteRange putInt(int val);
131
132  /**
133   * Store long {@code val} at the next position in this range.
134   * @param val the new value.
135   * @return this.
136   */
137  public PositionedByteRange putLong(long val);
138
139  /**
140   * Store the long {@code val} at the next position as a VLong
141   * @param val the value to store
142   * @return number of bytes written
143   */
144  public int putVLong(long val);
145
146  /**
147   * Store the content of {@code val} in this range, starting at the next position.
148   * @param val the new value.
149   * @return this.
150   */
151  public PositionedByteRange put(byte[] val);
152
153  /**
154   * Store {@code length} bytes from {@code val} into this range. Bytes from
155   * {@code val} are copied starting at {@code offset} into the range, starting at
156   * the current position.
157   * @param val the new value.
158   * @param offset the offset in {@code val} from which to start copying.
159   * @param length the number of bytes to copy from {@code val}.
160   * @return this.
161   */
162  public PositionedByteRange put(byte[] val, int offset, int length);
163
164  /**
165   * Limits the byte range upto a specified value. Limit cannot be greater than
166   * capacity
167   *
168   * @param limit
169   * @return PositionedByteRange
170   */
171  public PositionedByteRange setLimit(int limit);
172
173  /**
174   * Return the current limit
175   *
176   * @return limit
177   */
178  public int getLimit();
179
180  // override parent interface declarations to return this interface.
181
182  @Override
183  public PositionedByteRange unset();
184
185  @Override
186  public PositionedByteRange set(int capacity);
187
188  @Override
189  public PositionedByteRange set(byte[] bytes);
190
191  @Override
192  public PositionedByteRange set(byte[] bytes, int offset, int length);
193
194  @Override
195  public PositionedByteRange setOffset(int offset);
196
197  @Override
198  public PositionedByteRange setLength(int length);
199
200  @Override
201  public PositionedByteRange get(int index, byte[] dst);
202
203  @Override
204  public PositionedByteRange get(int index, byte[] dst, int offset, int length);
205
206  @Override
207  public PositionedByteRange put(int index, byte val);
208
209  @Override
210  public PositionedByteRange putShort(int index, short val);
211
212  @Override
213  public PositionedByteRange putInt(int index, int val);
214
215  @Override
216  public PositionedByteRange putLong(int index, long val);
217
218  @Override
219  public PositionedByteRange put(int index, byte[] val);
220
221  @Override
222  public PositionedByteRange put(int index, byte[] val, int offset, int length);
223
224  @Override
225  public PositionedByteRange deepCopy();
226
227  @Override
228  public PositionedByteRange shallowCopy();
229
230  @Override
231  public PositionedByteRange shallowCopySubRange(int innerOffset, int copyLength);
232}