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 */
79 byte[] getRowArray();
80
81 /**
82 * @return Array index of first row byte
83 */
84 int getRowOffset();
85
86 /**
87 * @return Number of row bytes. Must be < rowArray.length - offset.
88 */
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 */
99 byte[] getFamilyArray();
100
101 /**
102 * @return Array index of first family byte
103 */
104 int getFamilyOffset();
105
106 /**
107 * @return Number of family bytes. Must be < familyArray.length - offset.
108 */
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 */
119 byte[] getQualifierArray();
120
121 /**
122 * @return Array index of first qualifier byte
123 */
124 int getQualifierOffset();
125
126 /**
127 * @return Number of qualifier bytes. Must be < qualifierArray.length - offset.
128 */
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 */
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 */
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
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 */
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 */
179 byte[] getValueArray();
180
181 /**
182 * @return Array index of first value byte
183 */
184 int getValueOffset();
185
186 /**
187 * @return Number of value bytes. Must be < valueArray.length - offset.
188 */
189 int getValueLength();
190
191 /**
192 * @return the tags byte array
193 */
194 byte[] getTagsArray();
195
196 /**
197 * @return the first offset where the tags start in the Cell
198 */
199 int getTagsOffset();
200
201 /**
202 * @return the total length of the tags in the Cell.
203 */
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
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
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
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
244 byte[] getRow();
245 }