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; 20 21 import org.apache.hadoop.hbase.classification.InterfaceAudience; 22 import org.apache.hadoop.hbase.classification.InterfaceStability; 23 24 25 /** 26 * The unit of storage in HBase consisting of the following fields:<br/> 27 * <pre> 28 * 1) row 29 * 2) column family 30 * 3) column qualifier 31 * 4) timestamp 32 * 5) type 33 * 6) MVCC version 34 * 7) value 35 * </pre> 36 * <p/> 37 * Uniqueness is determined by the combination of row, column family, column qualifier, 38 * timestamp, and type. 39 * <p/> 40 * The natural comparator will perform a bitwise comparison on row, column family, and column 41 * qualifier. Less intuitively, it will then treat the greater timestamp as the lesser value with 42 * the goal of sorting newer cells first. 43 * <p/> 44 * This interface should not include methods that allocate new byte[]'s such as those used in client 45 * or debugging code. These users should use the methods found in the {@link CellUtil} class. 46 * Currently for to minimize the impact of existing applications moving between 0.94 and 0.96, we 47 * include the costly helper methods marked as deprecated. 48 * <p/> 49 * Cell implements Comparable<Cell> which is only meaningful when comparing to other keys in the 50 * same table. It uses CellComparator which does not work on the -ROOT- and hbase:meta tables. 51 * <p/> 52 * In the future, we may consider adding a boolean isOnHeap() method and a getValueBuffer() method 53 * that can be used to pass a value directly from an off-heap ByteBuffer to the network without 54 * copying into an on-heap byte[]. 55 * <p/> 56 * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as 57 * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate 58 * byte[]'s. 59 * <p/> 60 */ 61 @InterfaceAudience.Public 62 @InterfaceStability.Evolving 63 public interface Cell { 64 65 //1) Row 66 67 /** 68 * Contiguous raw bytes that may start at any index in the containing array. Max length is 69 * Short.MAX_VALUE which is 32,767 bytes. 70 * @return The array containing the row bytes. 71 */ 72 byte[] getRowArray(); 73 74 /** 75 * @return Array index of first row byte 76 */ 77 int getRowOffset(); 78 79 /** 80 * @return Number of row bytes. Must be < rowArray.length - offset. 81 */ 82 short getRowLength(); 83 84 85 //2) Family 86 87 /** 88 * Contiguous bytes composed of legal HDFS filename characters which may start at any index in the 89 * containing array. Max length is Byte.MAX_VALUE, which is 127 bytes. 90 * @return the array containing the family bytes. 91 */ 92 byte[] getFamilyArray(); 93 94 /** 95 * @return Array index of first family byte 96 */ 97 int getFamilyOffset(); 98 99 /** 100 * @return Number of family bytes. Must be < familyArray.length - offset. 101 */ 102 byte getFamilyLength(); 103 104 105 //3) Qualifier 106 107 /** 108 * Contiguous raw bytes that may start at any index in the containing array. Max length is 109 * Short.MAX_VALUE which is 32,767 bytes. 110 * @return The array containing the qualifier bytes. 111 */ 112 byte[] getQualifierArray(); 113 114 /** 115 * @return Array index of first qualifier byte 116 */ 117 int getQualifierOffset(); 118 119 /** 120 * @return Number of qualifier bytes. Must be < qualifierArray.length - offset. 121 */ 122 int getQualifierLength(); 123 124 125 //4) Timestamp 126 127 /** 128 * @return Long value representing time at which this cell was "Put" into the row. Typically 129 * represents the time of insertion, but can be any value from 0 to Long.MAX_VALUE. 130 */ 131 long getTimestamp(); 132 133 134 //5) Type 135 136 /** 137 * @return The byte representation of the KeyValue.TYPE of this cell: one of Put, Delete, etc 138 */ 139 byte getTypeByte(); 140 141 142 //6) MvccVersion 143 144 /** 145 * Internal use only. A region-specific sequence ID given to each operation. It always exists for 146 * cells in the memstore but is not retained forever. It may survive several flushes, but 147 * generally becomes irrelevant after the cell's row is no longer involved in any operations that 148 * require strict consistency. 149 * @return mvccVersion (always >= 0 if exists), or 0 if it no longer exists 150 */ 151 long getMvccVersion(); 152 153 154 //7) Value 155 156 /** 157 * Contiguous raw bytes that may start at any index in the containing array. Max length is 158 * Integer.MAX_VALUE which is 2,147,483,648 bytes. 159 * @return The array containing the value bytes. 160 */ 161 byte[] getValueArray(); 162 163 /** 164 * @return Array index of first value byte 165 */ 166 int getValueOffset(); 167 168 /** 169 * @return Number of value bytes. Must be < valueArray.length - offset. 170 */ 171 int getValueLength(); 172 173 /** 174 * @return the tags byte array 175 */ 176 @InterfaceStability.Unstable 177 byte[] getTagsArray(); 178 179 /** 180 * @return the first offset where the tags start in the Cell 181 */ 182 @InterfaceStability.Unstable 183 int getTagsOffset(); 184 185 /** 186 * @return the total length of the tags in the Cell. 187 * @deprecated use {@link #getTagsLengthUnsigned()} which can handle tags length upto 65535. 188 */ 189 @Deprecated 190 @InterfaceStability.Unstable 191 short getTagsLength(); 192 193 /** 194 * @return the total length of the tags in the Cell. 195 * @deprecated From next major version this will be renamed to getTagsLength() which returns int. 196 */ 197 @Deprecated 198 @InterfaceStability.Unstable 199 int getTagsLengthUnsigned(); 200 201 /** 202 * WARNING do not use, expensive. This gets an arraycopy of the cell's value. 203 * 204 * Added to ease transition from 0.94 -> 0.96. 205 * 206 * @deprecated as of 0.96, use {@link CellUtil#cloneValue(Cell)} 207 */ 208 @Deprecated 209 byte[] getValue(); 210 211 /** 212 * WARNING do not use, expensive. This gets an arraycopy of the cell's family. 213 * 214 * Added to ease transition from 0.94 -> 0.96. 215 * 216 * @deprecated as of 0.96, use {@link CellUtil#cloneFamily(Cell)} 217 */ 218 @Deprecated 219 byte[] getFamily(); 220 221 /** 222 * WARNING do not use, expensive. This gets an arraycopy of the cell's qualifier. 223 * 224 * Added to ease transition from 0.94 -> 0.96. 225 * 226 * @deprecated as of 0.96, use {@link CellUtil#cloneQualifier(Cell)} 227 */ 228 @Deprecated 229 byte[] getQualifier(); 230 231 /** 232 * WARNING do not use, expensive. this gets an arraycopy of the cell's row. 233 * 234 * Added to ease transition from 0.94 -> 0.96. 235 * 236 * @deprecated as of 0.96, use {@link CellUtil#getRowByte(Cell, int)} 237 */ 238 @Deprecated 239 byte[] getRow(); 240 }