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.classification.InterfaceAudience; 22 import org.apache.hadoop.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 does not include methods that allocate new byte[]'s such as those used in client 45 * or debugging code. These should be placed in a sub-interface or the {@link CellUtil} class. 46 * <p/> 47 * Cell implements Comparable<Cell> which is only meaningful when comparing to other keys in the 48 * same table. It uses CellComparator which does not work on the -ROOT- and .META. tables. 49 * <p/> 50 * In the future, we may consider adding a boolean isOnHeap() method and a getValueBuffer() method 51 * that can be used to pass a value directly from an off-heap ByteBuffer to the network without 52 * copying into an on-heap byte[]. 53 * <p/> 54 * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as 55 * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate 56 * byte[]'s. 57 * <p/> 58 */ 59 @InterfaceAudience.Private 60 @InterfaceStability.Evolving 61 public interface Cell { 62 63 //1) Row 64 65 /** 66 * Contiguous raw bytes that may start at any index in the containing array. Max length is 67 * Short.MAX_VALUE which is 32,767 bytes. 68 * @return The array containing the row bytes. 69 */ 70 byte[] getRowArray(); 71 72 /** 73 * @return Array index of first row byte 74 */ 75 int getRowOffset(); 76 77 /** 78 * @return Number of row bytes. Must be < rowArray.length - offset. 79 */ 80 short getRowLength(); 81 82 83 //2) Family 84 85 /** 86 * Contiguous bytes composed of legal HDFS filename characters which may start at any index in the 87 * containing array. Max length is Byte.MAX_VALUE, which is 127 bytes. 88 * @return the array containing the family bytes. 89 */ 90 byte[] getFamilyArray(); 91 92 /** 93 * @return Array index of first row byte 94 */ 95 int getFamilyOffset(); 96 97 /** 98 * @return Number of family bytes. Must be < familyArray.length - offset. 99 */ 100 byte getFamilyLength(); 101 102 103 //3) Qualifier 104 105 /** 106 * Contiguous raw bytes that may start at any index in the containing array. Max length is 107 * Short.MAX_VALUE which is 32,767 bytes. 108 * @return The array containing the qualifier bytes. 109 */ 110 byte[] getQualifierArray(); 111 112 /** 113 * @return Array index of first qualifier byte 114 */ 115 int getQualifierOffset(); 116 117 /** 118 * @return Number of qualifier bytes. Must be < qualifierArray.length - offset. 119 */ 120 int getQualifierLength(); 121 122 123 //4) Timestamp 124 125 /** 126 * @return Long value representing time at which this cell was "Put" into the row. Typically 127 * represents the time of insertion, but can be any value from Long.MIN_VALUE to Long.MAX_VALUE. 128 */ 129 long getTimestamp(); 130 131 132 //5) Type 133 134 /** 135 * @return The byte representation of the KeyValue.TYPE of this cell: one of Put, Delete, etc 136 */ 137 byte getTypeByte(); 138 139 140 //6) MvccVersion 141 142 /** 143 * Internal use only. A region-specific sequence ID given to each operation. It always exists for 144 * cells in the memstore but is not retained forever. It may survive several flushes, but 145 * generally becomes irrelevant after the cell's row is no longer involved in any operations that 146 * require strict consistency. 147 * @return mvccVersion (always >= 0 if exists), or 0 if it no longer exists 148 */ 149 long getMvccVersion(); 150 151 152 //7) Value 153 154 /** 155 * Contiguous raw bytes that may start at any index in the containing array. Max length is 156 * Integer.MAX_VALUE which is 2,147,483,648 bytes. 157 * @return The array containing the value bytes. 158 */ 159 byte[] getValueArray(); 160 161 /** 162 * @return Array index of first value byte 163 */ 164 int getValueOffset(); 165 166 /** 167 * @return Number of value bytes. Must be < valueArray.length - offset. 168 */ 169 int getValueLength(); 170 171 }