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   * This interface should not include methods that allocate new byte[]'s such as those used in client
48   * or debugging code. These users should use the methods found in the {@link CellUtil} class.
49   * Currently for to minimize the impact of existing applications moving between 0.94 and 0.96, we
50   * include the costly helper methods marked as deprecated.   
51   * </p>
52   * <p>
53   * Cell implements Comparable&lt;Cell&gt; which is only meaningful when
54   * comparing to other keys in the
55   * same table. It uses CellComparator which does not work on the -ROOT- and hbase:meta tables.
56   * </p>
57   * <p>
58   * In the future, we may consider adding a boolean isOnHeap() method and a getValueBuffer() method
59   * that can be used to pass a value directly from an off-heap ByteBuffer to the network without
60   * copying into an on-heap byte[].
61   * </p>
62   * <p>
63   * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as
64   * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate
65   * byte[]'s.
66   * </p>
67   */
68  @InterfaceAudience.Public
69  @InterfaceStability.Evolving
70  public interface Cell {
71  
72    //1) Row
73  
74    /**
75     * Contiguous raw bytes that may start at any index in the containing array. Max length is
76     * Short.MAX_VALUE which is 32,767 bytes.
77     * @return The array containing the row bytes.
78     */
79    byte[] getRowArray();
80  
81    /**
82     * @return Array index of first row byte
83     */
84    int getRowOffset();
85  
86    /**
87     * @return Number of row bytes. Must be &lt; rowArray.length - offset.
88     */
89    short getRowLength();
90  
91  
92    //2) Family
93  
94    /**
95     * Contiguous bytes composed of legal HDFS filename characters which may start at any index in the
96     * containing array. Max length is Byte.MAX_VALUE, which is 127 bytes.
97     * @return the array containing the family bytes.
98     */
99    byte[] getFamilyArray();
100 
101   /**
102    * @return Array index of first family byte
103    */
104   int getFamilyOffset();
105 
106   /**
107    * @return Number of family bytes.  Must be &lt; familyArray.length - offset.
108    */
109   byte getFamilyLength();
110 
111 
112   //3) Qualifier
113 
114   /**
115    * Contiguous raw bytes that may start at any index in the containing array. Max length is
116    * Short.MAX_VALUE which is 32,767 bytes.
117    * @return The array containing the qualifier bytes.
118    */
119   byte[] getQualifierArray();
120 
121   /**
122    * @return Array index of first qualifier byte
123    */
124   int getQualifierOffset();
125 
126   /**
127    * @return Number of qualifier bytes.  Must be &lt; qualifierArray.length - offset.
128    */
129   int getQualifierLength();
130 
131 
132   //4) Timestamp
133 
134   /**
135    * @return Long value representing time at which this cell was "Put" into the row.  Typically
136    * represents the time of insertion, but can be any value from 0 to Long.MAX_VALUE.
137    */
138   long getTimestamp();
139 
140 
141   //5) Type
142 
143   /**
144    * @return The byte representation of the KeyValue.TYPE of this cell: one of Put, Delete, etc
145    */
146   byte getTypeByte();
147 
148 
149   //6) MvccVersion
150 
151   /**
152    * @deprecated as of 1.0, use {@link Cell#getSequenceId()}
153    * 
154    * Internal use only. A region-specific sequence ID given to each operation. It always exists for
155    * cells in the memstore but is not retained forever. It may survive several flushes, but
156    * generally becomes irrelevant after the cell's row is no longer involved in any operations that
157    * require strict consistency.
158    * @return mvccVersion (always &gt;= 0 if exists), or 0 if it no longer exists
159    */
160   @Deprecated
161   long getMvccVersion();
162 
163   /**
164    * A region-specific unique monotonically increasing sequence ID given to each Cell. It always
165    * exists for cells in the memstore but is not retained forever. It will be kept for
166    * {@link HConstants#KEEP_SEQID_PERIOD} days, but generally becomes irrelevant after the cell's
167    * row is no longer involved in any operations that require strict consistency.
168    * @return seqId (always &gt; 0 if exists), or 0 if it no longer exists
169    */
170   long getSequenceId();
171 
172   //7) Value
173 
174   /**
175    * Contiguous raw bytes that may start at any index in the containing array. Max length is
176    * Integer.MAX_VALUE which is 2,147,483,648 bytes.
177    * @return The array containing the value bytes.
178    */
179   byte[] getValueArray();
180 
181   /**
182    * @return Array index of first value byte
183    */
184   int getValueOffset();
185 
186   /**
187    * @return Number of value bytes.  Must be &lt; valueArray.length - offset.
188    */
189   int getValueLength();
190   
191   /**
192    * @return the tags byte array
193    */
194   byte[] getTagsArray();
195 
196   /**
197    * @return the first offset where the tags start in the Cell
198    */
199   int getTagsOffset();
200 
201   /**
202    * @return the total length of the tags in the Cell.
203    */
204   int getTagsLength();
205   
206   /**
207    * WARNING do not use, expensive.  This gets an arraycopy of the cell's value.
208    *
209    * Added to ease transition from  0.94 -&gt; 0.96.
210    * 
211    * @deprecated as of 0.96, use {@link CellUtil#cloneValue(Cell)}
212    */
213   @Deprecated
214   byte[] getValue();
215   
216   /**
217    * WARNING do not use, expensive.  This gets an arraycopy of the cell's family. 
218    *
219    * Added to ease transition from  0.94 -&gt; 0.96.
220    * 
221    * @deprecated as of 0.96, use {@link CellUtil#cloneFamily(Cell)}
222    */
223   @Deprecated
224   byte[] getFamily();
225 
226   /**
227    * WARNING do not use, expensive.  This gets an arraycopy of the cell's qualifier.
228    *
229    * Added to ease transition from  0.94 -&gt; 0.96.
230    * 
231    * @deprecated as of 0.96, use {@link CellUtil#cloneQualifier(Cell)}
232    */
233   @Deprecated
234   byte[] getQualifier();
235 
236   /**
237    * WARNING do not use, expensive.  this gets an arraycopy of the cell's row.
238    *
239    * Added to ease transition from  0.94 -&gt; 0.96.
240    * 
241    * @deprecated as of 0.96, use {@link CellUtil#getRowByte(Cell, int)}
242    */
243   @Deprecated
244   byte[] getRow();
245 }