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