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 * @deprecated as of 1.0, use {@link Cell#getSequenceId()}
146 *
147 * Internal use only. A region-specific sequence ID given to each operation. It always exists for
148 * cells in the memstore but is not retained forever. It may survive several flushes, but
149 * generally becomes irrelevant after the cell's row is no longer involved in any operations that
150 * require strict consistency.
151 * @return mvccVersion (always >= 0 if exists), or 0 if it no longer exists
152 */
153 @Deprecated
154 long getMvccVersion();
155
156 /**
157 * A region-specific unique monotonically increasing sequence ID given to each Cell. It always
158 * exists for cells in the memstore but is not retained forever. It will be kept for
159 * {@link HConstants#KEEP_SEQID_PERIOD} days, but generally becomes irrelevant after the cell's
160 * row is no longer involved in any operations that require strict consistency.
161 * @return seqId (always > 0 if exists), or 0 if it no longer exists
162 */
163 long getSequenceId();
164
165 //7) Value
166
167 /**
168 * Contiguous raw bytes that may start at any index in the containing array. Max length is
169 * Integer.MAX_VALUE which is 2,147,483,648 bytes.
170 * @return The array containing the value bytes.
171 */
172 byte[] getValueArray();
173
174 /**
175 * @return Array index of first value byte
176 */
177 int getValueOffset();
178
179 /**
180 * @return Number of value bytes. Must be < valueArray.length - offset.
181 */
182 int getValueLength();
183
184 /**
185 * @return the tags byte array
186 */
187 byte[] getTagsArray();
188
189 /**
190 * @return the first offset where the tags start in the Cell
191 */
192 int getTagsOffset();
193
194 /**
195 * @return the total length of the tags in the Cell.
196 */
197 int getTagsLength();
198
199 /**
200 * WARNING do not use, expensive. This gets an arraycopy of the cell's value.
201 *
202 * Added to ease transition from 0.94 -> 0.96.
203 *
204 * @deprecated as of 0.96, use {@link CellUtil#cloneValue(Cell)}
205 */
206 @Deprecated
207 byte[] getValue();
208
209 /**
210 * WARNING do not use, expensive. This gets an arraycopy of the cell's family.
211 *
212 * Added to ease transition from 0.94 -> 0.96.
213 *
214 * @deprecated as of 0.96, use {@link CellUtil#cloneFamily(Cell)}
215 */
216 @Deprecated
217 byte[] getFamily();
218
219 /**
220 * WARNING do not use, expensive. This gets an arraycopy of the cell's qualifier.
221 *
222 * Added to ease transition from 0.94 -> 0.96.
223 *
224 * @deprecated as of 0.96, use {@link CellUtil#cloneQualifier(Cell)}
225 */
226 @Deprecated
227 byte[] getQualifier();
228
229 /**
230 * WARNING do not use, expensive. this gets an arraycopy of the cell's row.
231 *
232 * Added to ease transition from 0.94 -> 0.96.
233 *
234 * @deprecated as of 0.96, use {@link CellUtil#getRowByte(Cell, int)}
235 */
236 @Deprecated
237 byte[] getRow();
238 }