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 * Lightweight, reusable class for specifying ranges of byte[]'s. 024 * <p> 025 * {@code ByteRange} maintains an underlying byte[] and a viewport into that byte[] as a range of 026 * bytes. The {@code ByteRange} is a mutable, reusable object, so the underlying byte[] can be 027 * modified after instantiation. This is done using the {@link #set(byte[])} and {@link #unset()} 028 * methods. Direct access to the byte[] is also available via {@link #getBytes()}. The viewport is 029 * defined by an {@code offset} into the byte[] and a {@code length}. The range of bytes is 030 * 0-indexed, and is accessed by index via the {@link #get(int)} and {@link #put(int, byte)} 031 * methods. 032 * </p> 033 * <p> 034 * This interface differs from ByteBuffer: 035 * </p> 036 * <ul> 037 * <li>On-heap bytes only</li> 038 * <li>Raw {@code byte} access only; does not encode other primitives.</li> 039 * <li>Implements {@code equals(Object)}, {@code #hashCode()}, and {@code #compareTo(ByteRange)} so 040 * that it can be used in standard java Collections. Comparison operations are lexicographic, which 041 * is native to HBase.</li> 042 * <li>Allows the addition of simple core methods like the deep and shallow copy methods.</li> 043 * <li>Can be reused in tight loops like a major compaction which can save significant amounts of 044 * garbage. (Without reuse, we throw off garbage like 045 * <a href="http://www.youtube.com/watch?v=lkmBH-MjZF4">this thing</a>.)</li> 046 * </ul> 047 * <p> 048 * Mutable, and always evaluates {@code #equals(Object)}, {@code #hashCode()}, and 049 * {@code #compareTo(ByteRange)} based on the current contents. 050 * </p> 051 * <p> 052 * Can contain convenience methods for comparing, printing, cloning, spawning new arrays, copying to 053 * other arrays, etc. Please place non-core methods into {@link ByteRangeUtils}. 054 * </p> 055 */ 056@InterfaceAudience.Public 057public interface ByteRange extends Comparable<ByteRange> { 058 059 /** 060 * The underlying byte[]. 061 */ 062 public byte[] getBytes(); 063 064 /** 065 * Nullifies this ByteRange. That is, it becomes a husk, being a range over no byte[] whatsoever. 066 * n 067 */ 068 public ByteRange unset(); 069 070 /** 071 * Reuse this {@code ByteRange} over a new byte[]. {@code offset} is set to 0 and {@code length} 072 * is set to {@code capacity}. 073 * @param capacity the size of a new byte[]. n 074 */ 075 public ByteRange set(int capacity); 076 077 /** 078 * Reuse this {@code ByteRange} over a new byte[]. {@code offset} is set to 0 and {@code length} 079 * is set to {@code bytes.length}. A null {@code bytes} IS supported, in which case this method 080 * will behave equivalently to {@link #unset()}. 081 * @param bytes the array to wrap. n 082 */ 083 public ByteRange set(byte[] bytes); 084 085 /** 086 * Reuse this {@code ByteRange} over a new byte[]. A null {@code bytes} IS supported, in which 087 * case this method will behave equivalently to {@link #unset()}, regardless of the values of 088 * {@code offset} and {@code length}. 089 * @param bytes The array to wrap. 090 * @param offset The offset into {@code bytes} considered the beginning of this range. 091 * @param length The length of this range. 092 * @return this. 093 */ 094 public ByteRange set(byte[] bytes, int offset, int length); 095 096 /** 097 * The offset, the index into the underlying byte[] at which this range begins. 098 * @see #getBytes() 099 */ 100 public int getOffset(); 101 102 /** 103 * Update the beginning of this range. {@code offset + length} may not be greater than 104 * {@code bytes.length}. 105 * @param offset the new start of this range. 106 * @return this. 107 */ 108 public ByteRange setOffset(int offset); 109 110 /** 111 * The length of the range. 112 */ 113 public int getLength(); 114 115 /** 116 * Update the length of this range. {@code offset + length} should not be greater than 117 * {@code bytes.length}. 118 * @param length The new length of this range. 119 * @return this. 120 */ 121 public ByteRange setLength(int length); 122 123 /** Returns true when this range is of zero length, false otherwise. */ 124 public boolean isEmpty(); 125 126 /** 127 * Retrieve the byte at {@code index}. 128 * @param index zero-based index into this range. 129 * @return single byte at index. 130 */ 131 public byte get(int index); 132 133 /** 134 * Retrieve the short value at {@code index} 135 * @param index zero-based index into this range 136 * @return the short value at {@code index} 137 */ 138 public short getShort(int index); 139 140 /** 141 * Retrieve the int value at {@code index} 142 * @param index zero-based index into this range 143 * @return the int value at {@code index} 144 */ 145 public int getInt(int index); 146 147 /** 148 * Retrieve the long value at {@code index} 149 * @param index zero-based index into this range 150 * @return the long value at {@code index} 151 */ 152 public long getLong(int index); 153 154 /** 155 * Retrieve the long value at {@code index} which is stored as VLong 156 * @param index zero-based index into this range 157 * @return the long value at {@code index} which is stored as VLong 158 */ 159 public long getVLong(int index); 160 161 /** 162 * Fill {@code dst} with bytes from the range, starting from {@code index}. 163 * @param index zero-based index into this range. 164 * @param dst the destination of the copy. 165 * @return this. 166 */ 167 public ByteRange get(int index, byte[] dst); 168 169 /** 170 * Fill {@code dst} with bytes from the range, starting from {@code index}. {@code length} bytes 171 * are copied into {@code dst}, starting at {@code offset}. 172 * @param index zero-based index into this range. 173 * @param dst the destination of the copy. 174 * @param offset the offset into {@code dst} to start the copy. 175 * @param length the number of bytes to copy into {@code dst}. 176 * @return this. 177 */ 178 public ByteRange get(int index, byte[] dst, int offset, int length); 179 180 /** 181 * Store {@code val} at {@code index}. 182 * @param index the index in the range where {@code val} is stored. 183 * @param val the value to store. 184 * @return this. 185 */ 186 public ByteRange put(int index, byte val); 187 188 /** 189 * Store the short value at {@code index} 190 * @param index the index in the range where {@code val} is stored 191 * @param val the value to store n 192 */ 193 public ByteRange putShort(int index, short val); 194 195 /** 196 * Store the int value at {@code index} 197 * @param index the index in the range where {@code val} is stored 198 * @param val the value to store n 199 */ 200 public ByteRange putInt(int index, int val); 201 202 /** 203 * Store the long value at {@code index} 204 * @param index the index in the range where {@code val} is stored 205 * @param val the value to store n 206 */ 207 public ByteRange putLong(int index, long val); 208 209 /** 210 * Store the long value at {@code index} as a VLong 211 * @param index the index in the range where {@code val} is stored 212 * @param val the value to store 213 * @return number of bytes written 214 */ 215 public int putVLong(int index, long val); 216 217 /** 218 * Store {@code val} at {@code index}. 219 * @param index the index in the range where {@code val} is stored. 220 * @param val the value to store. 221 * @return this. 222 */ 223 public ByteRange put(int index, byte[] val); 224 225 /** 226 * Store {@code length} bytes from {@code val} into this range, starting at {@code index}. Bytes 227 * from {@code val} are copied starting at {@code offset} into the range. 228 * @param index position in this range to start the copy. 229 * @param val the value to store. 230 * @param offset the offset in {@code val} from which to start copying. 231 * @param length the number of bytes to copy from {@code val}. 232 * @return this. 233 */ 234 public ByteRange put(int index, byte[] val, int offset, int length); 235 236 /** 237 * Instantiate a new byte[] with exact length, which is at least 24 bytes + length. Copy the 238 * contents of this range into it. 239 * @return The newly cloned byte[]. 240 */ 241 public byte[] deepCopyToNewArray(); 242 243 /** 244 * Create a new {@code ByteRange} with new backing byte[] containing a copy of the content from 245 * {@code this} range's window. 246 * @return Deep copy 247 */ 248 public ByteRange deepCopy(); 249 250 /** 251 * Wrapper for System.arraycopy. Copy the contents of this range into the provided array. 252 * @param destination Copy to this array 253 * @param destinationOffset First index in the destination array. 254 */ 255 public void deepCopyTo(byte[] destination, int destinationOffset); 256 257 /** 258 * Wrapper for System.arraycopy. Copy the contents of this range into the provided array. 259 * @param innerOffset Start copying from this index in this source ByteRange. First byte 260 * copied is bytes[offset + innerOffset] 261 * @param copyLength Copy this many bytes 262 * @param destination Copy to this array 263 * @param destinationOffset First index in the destination array. 264 */ 265 public void deepCopySubRangeTo(int innerOffset, int copyLength, byte[] destination, 266 int destinationOffset); 267 268 /** 269 * Create a new {@code ByteRange} that points at this range's byte[]. Modifying the shallowCopy 270 * will modify the bytes in this range's array. Pass over the hash code if it is already cached. 271 * @return new {@code ByteRange} object referencing this range's byte[]. 272 */ 273 public ByteRange shallowCopy(); 274 275 /** 276 * Create a new {@code ByteRange} that points at this range's byte[]. The new range can have 277 * different values for offset and length, but modifying the shallowCopy will modify the bytes in 278 * this range's array. Pass over the hash code if it is already cached. 279 * @param innerOffset First byte of clone will be this.offset + copyOffset. 280 * @param copyLength Number of bytes in the clone. 281 * @return new {@code ByteRange} object referencing this range's byte[]. 282 */ 283 public ByteRange shallowCopySubRange(int innerOffset, int copyLength); 284 285}