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