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 * Cell implements Comparable<Cell> which is only meaningful when 48 * comparing to other keys in the 49 * same table. It uses CellComparator which does not work on the -ROOT- and hbase:meta tables. 50 * </p> 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 * <p> 57 * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as 58 * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate 59 * byte[]'s. 60 * </p> 61 */ 62 @InterfaceAudience.Public 63 @InterfaceStability.Evolving 64 public interface Cell { 65 66 //1) Row 67 68 /** 69 * Contiguous raw bytes that may start at any index in the containing array. Max length is 70 * Short.MAX_VALUE which is 32,767 bytes. 71 * @return The array containing the row bytes. 72 */ 73 byte[] getRowArray(); 74 75 /** 76 * @return Array index of first row byte 77 */ 78 int getRowOffset(); 79 80 /** 81 * @return Number of row bytes. Must be < rowArray.length - offset. 82 */ 83 short getRowLength(); 84 85 86 //2) Family 87 88 /** 89 * Contiguous bytes composed of legal HDFS filename characters which may start at any index in the 90 * containing array. Max length is Byte.MAX_VALUE, which is 127 bytes. 91 * @return the array containing the family bytes. 92 */ 93 byte[] getFamilyArray(); 94 95 /** 96 * @return Array index of first family byte 97 */ 98 int getFamilyOffset(); 99 100 /** 101 * @return Number of family bytes. Must be < familyArray.length - offset. 102 */ 103 byte getFamilyLength(); 104 105 106 //3) Qualifier 107 108 /** 109 * Contiguous raw bytes that may start at any index in the containing array. Max length is 110 * Short.MAX_VALUE which is 32,767 bytes. 111 * @return The array containing the qualifier bytes. 112 */ 113 byte[] getQualifierArray(); 114 115 /** 116 * @return Array index of first qualifier byte 117 */ 118 int getQualifierOffset(); 119 120 /** 121 * @return Number of qualifier bytes. Must be < qualifierArray.length - offset. 122 */ 123 int getQualifierLength(); 124 125 126 //4) Timestamp 127 128 /** 129 * @return Long value representing time at which this cell was "Put" into the row. Typically 130 * represents the time of insertion, but can be any value from 0 to Long.MAX_VALUE. 131 */ 132 long getTimestamp(); 133 134 135 //5) Type 136 137 /** 138 * @return The byte representation of the KeyValue.TYPE of this cell: one of Put, Delete, etc 139 */ 140 byte getTypeByte(); 141 142 143 //6) SequenceId 144 145 /** 146 * A region-specific unique monotonically increasing sequence ID given to each Cell. It always 147 * exists for cells in the memstore but is not retained forever. It will be kept for 148 * {@link HConstants#KEEP_SEQID_PERIOD} days, but generally becomes irrelevant after the cell's 149 * row is no longer involved in any operations that require strict consistency. 150 * @return seqId (always > 0 if exists), or 0 if it no longer exists 151 */ 152 long getSequenceId(); 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 byte[] getTagsArray(); 177 178 /** 179 * @return the first offset where the tags start in the Cell 180 */ 181 int getTagsOffset(); 182 183 /** 184 * @return the total length of the tags in the Cell. 185 */ 186 int getTagsLength(); 187 }