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 family 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 /**
172 * @return the tags byte array
173 */
174 byte[] getTagsArray();
175
176 /**
177 * @return the first offset where the tags start in the Cell
178 */
179 int getTagsOffset();
180
181 /**
182 * @return the total length of the tags in the Cell.
183 */
184 int getTagsLength();
185
186 }