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