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.hbase.classification.InterfaceAudience; 24 import org.apache.hadoop.hbase.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 }