View Javadoc

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&lt;Cell&gt; 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 &lt; 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 &lt; 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.
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 &lt; 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) SequenceId
143
144   /**
145    * A region-specific unique monotonically increasing sequence ID given to each Cell. It always
146    * exists for cells in the memstore but is not retained forever. It will be kept for
147    * {@link HConstants#KEEP_SEQID_PERIOD} days, but generally becomes irrelevant after the cell's
148    * row is no longer involved in any operations that require strict consistency.
149    * @return seqId (always &gt; 0 if exists), or 0 if it no longer exists
150    */
151   long getSequenceId();
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,647 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 &lt; valueArray.length - offset.
169    */
170   int getValueLength();
171
172   /**
173    * @return the tags byte array
174    */
175   byte[] getTagsArray();
176
177   /**
178    * @return the first offset where the tags start in the Cell
179    */
180   int getTagsOffset();
181
182   /**
183    * @return the total length of the tags in the Cell.
184    */
185   int getTagsLength();
186 }