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 }