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 */ 067 public ByteRange unset(); 068 069 /** 070 * Reuse this {@code ByteRange} over a new byte[]. {@code offset} is set to 0 and {@code length} 071 * is set to {@code capacity}. 072 * @param capacity the size of a new byte[]. 073 */ 074 public ByteRange set(int capacity); 075 076 /** 077 * Reuse this {@code ByteRange} over a new byte[]. {@code offset} is set to 0 and {@code length} 078 * is set to {@code bytes.length}. A null {@code bytes} IS supported, in which case this method 079 * will behave equivalently to {@link #unset()}. 080 * @param bytes the array to wrap. 081 */ 082 public ByteRange set(byte[] bytes); 083 084 /** 085 * Reuse this {@code ByteRange} over a new byte[]. A null {@code bytes} IS supported, in which 086 * case this method will behave equivalently to {@link #unset()}, regardless of the values of 087 * {@code offset} and {@code length}. 088 * @param bytes The array to wrap. 089 * @param offset The offset into {@code bytes} considered the beginning of this range. 090 * @param length The length of this range. 091 * @return this. 092 */ 093 public ByteRange set(byte[] bytes, int offset, int length); 094 095 /** 096 * The offset, the index into the underlying byte[] at which this range begins. 097 * @see #getBytes() 098 */ 099 public int getOffset(); 100 101 /** 102 * Update the beginning of this range. {@code offset + length} may not be greater than 103 * {@code bytes.length}. 104 * @param offset the new start of this range. 105 * @return this. 106 */ 107 public ByteRange setOffset(int offset); 108 109 /** 110 * The length of the range. 111 */ 112 public int getLength(); 113 114 /** 115 * Update the length of this range. {@code offset + length} should not be greater than 116 * {@code bytes.length}. 117 * @param length The new length of this range. 118 * @return this. 119 */ 120 public ByteRange setLength(int length); 121 122 /** Returns true when this range is of zero length, false otherwise. */ 123 public boolean isEmpty(); 124 125 /** 126 * Retrieve the byte at {@code index}. 127 * @param index zero-based index into this range. 128 * @return single byte at index. 129 */ 130 public byte get(int index); 131 132 /** 133 * Retrieve the short value at {@code index} 134 * @param index zero-based index into this range 135 * @return the short value at {@code index} 136 */ 137 public short getShort(int index); 138 139 /** 140 * Retrieve the int value at {@code index} 141 * @param index zero-based index into this range 142 * @return the int value at {@code index} 143 */ 144 public int getInt(int index); 145 146 /** 147 * Retrieve the long value at {@code index} 148 * @param index zero-based index into this range 149 * @return the long value at {@code index} 150 */ 151 public long getLong(int index); 152 153 /** 154 * Retrieve the long value at {@code index} which is stored as VLong 155 * @param index zero-based index into this range 156 * @return the long value at {@code index} which is stored as VLong 157 */ 158 public long getVLong(int index); 159 160 /** 161 * Fill {@code dst} with bytes from the range, starting from {@code index}. 162 * @param index zero-based index into this range. 163 * @param dst the destination of the copy. 164 * @return this. 165 */ 166 public ByteRange get(int index, byte[] dst); 167 168 /** 169 * Fill {@code dst} with bytes from the range, starting from {@code index}. {@code length} bytes 170 * are copied into {@code dst}, starting at {@code offset}. 171 * @param index zero-based index into this range. 172 * @param dst the destination of the copy. 173 * @param offset the offset into {@code dst} to start the copy. 174 * @param length the number of bytes to copy into {@code dst}. 175 * @return this. 176 */ 177 public ByteRange get(int index, byte[] dst, int offset, int length); 178 179 /** 180 * Store {@code val} at {@code index}. 181 * @param index the index in the range where {@code val} is stored. 182 * @param val the value to store. 183 * @return this. 184 */ 185 public ByteRange put(int index, byte val); 186 187 /** 188 * Store the short value at {@code index} 189 * @param index the index in the range where {@code val} is stored 190 * @param val the value to store 191 */ 192 public ByteRange putShort(int index, short val); 193 194 /** 195 * Store the int value at {@code index} 196 * @param index the index in the range where {@code val} is stored 197 * @param val the value to store 198 */ 199 public ByteRange putInt(int index, int val); 200 201 /** 202 * Store the long value at {@code index} 203 * @param index the index in the range where {@code val} is stored 204 * @param val the value to store 205 */ 206 public ByteRange putLong(int index, long val); 207 208 /** 209 * Store the long value at {@code index} as a VLong 210 * @param index the index in the range where {@code val} is stored 211 * @param val the value to store 212 * @return number of bytes written 213 */ 214 public int putVLong(int index, long val); 215 216 /** 217 * Store {@code val} at {@code index}. 218 * @param index the index in the range where {@code val} is stored. 219 * @param val the value to store. 220 * @return this. 221 */ 222 public ByteRange put(int index, byte[] val); 223 224 /** 225 * Store {@code length} bytes from {@code val} into this range, starting at {@code index}. Bytes 226 * from {@code val} are copied starting at {@code offset} into the range. 227 * @param index position in this range to start the copy. 228 * @param val the value to store. 229 * @param offset the offset in {@code val} from which to start copying. 230 * @param length the number of bytes to copy from {@code val}. 231 * @return this. 232 */ 233 public ByteRange put(int index, byte[] val, int offset, int length); 234 235 /** 236 * Instantiate a new byte[] with exact length, which is at least 24 bytes + length. Copy the 237 * contents of this range into it. 238 * @return The newly cloned byte[]. 239 */ 240 public byte[] deepCopyToNewArray(); 241 242 /** 243 * Create a new {@code ByteRange} with new backing byte[] containing a copy of the content from 244 * {@code this} range's window. 245 * @return Deep copy 246 */ 247 public ByteRange deepCopy(); 248 249 /** 250 * Wrapper for System.arraycopy. Copy the contents of this range into the provided array. 251 * @param destination Copy to this array 252 * @param destinationOffset First index in the destination array. 253 */ 254 public void deepCopyTo(byte[] destination, int destinationOffset); 255 256 /** 257 * Wrapper for System.arraycopy. Copy the contents of this range into the provided array. 258 * @param innerOffset Start copying from this index in this source ByteRange. First byte 259 * copied is bytes[offset + innerOffset] 260 * @param copyLength Copy this many bytes 261 * @param destination Copy to this array 262 * @param destinationOffset First index in the destination array. 263 */ 264 public void deepCopySubRangeTo(int innerOffset, int copyLength, byte[] destination, 265 int destinationOffset); 266 267 /** 268 * Create a new {@code ByteRange} that points at this range's byte[]. Modifying the shallowCopy 269 * will modify the bytes in this range's array. Pass over the hash code if it is already cached. 270 * @return new {@code ByteRange} object referencing this range's byte[]. 271 */ 272 public ByteRange shallowCopy(); 273 274 /** 275 * Create a new {@code ByteRange} that points at this range's byte[]. The new range can have 276 * different values for offset and length, but modifying the shallowCopy will modify the bytes in 277 * this range's array. Pass over the hash code if it is already cached. 278 * @param innerOffset First byte of clone will be this.offset + copyOffset. 279 * @param copyLength Number of bytes in the clone. 280 * @return new {@code ByteRange} object referencing this range's byte[]. 281 */ 282 public ByteRange shallowCopySubRange(int innerOffset, int copyLength); 283 284}