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    * Internal use only. A region-specific sequence ID given to each operation. It always exists for
146    * cells in the memstore but is not retained forever. It may survive several flushes, but
147    * generally becomes irrelevant after the cell's row is no longer involved in any operations that
148    * require strict consistency.
149    * @return mvccVersion (always >= 0 if exists), or 0 if it no longer exists
150    */
151   long getMvccVersion();
152 
153 
154   //7) Value
155 
156   /**
157    * Contiguous raw bytes that may start at any index in the containing array. Max length is
158    * Integer.MAX_VALUE which is 2,147,483,648 bytes.
159    * @return The array containing the value bytes.
160    */
161   byte[] getValueArray();
162 
163   /**
164    * @return Array index of first value byte
165    */
166   int getValueOffset();
167 
168   /**
169    * @return Number of value bytes.  Must be < valueArray.length - offset.
170    */
171   int getValueLength();
172   
173   /**
174    * @return the tags byte array
175    */
176   byte[] getTagsArray();
177 
178   /**
179    * @return the first offset where the tags start in the Cell
180    */
181   int getTagsOffset();
182 
183   /**
184    * @return the total length of the tags in the Cell.
185    * @deprecated use {@link #getTagsLengthUnsigned()} which can handle tags length upto 65535.
186    */
187   @Deprecated
188   short getTagsLength();
189 
190   /**
191    * @return the total length of the tags in the Cell.
192    * @deprecated From next major version this will be renamed to getTagsLength() which returns int.
193    */
194   @Deprecated
195   int getTagsLengthUnsigned();
196   
197   /**
198    * WARNING do not use, expensive.  This gets an arraycopy of the cell's value.
199    *
200    * Added to ease transition from  0.94 -> 0.96.
201    * 
202    * @deprecated as of 0.96, use {@link CellUtil#cloneValue(Cell)}
203    */
204   @Deprecated
205   byte[] getValue();
206   
207   /**
208    * WARNING do not use, expensive.  This gets an arraycopy of the cell's family. 
209    *
210    * Added to ease transition from  0.94 -> 0.96.
211    * 
212    * @deprecated as of 0.96, use {@link CellUtil#cloneFamily(Cell)}
213    */
214   @Deprecated
215   byte[] getFamily();
216 
217   /**
218    * WARNING do not use, expensive.  This gets an arraycopy of the cell's qualifier.
219    *
220    * Added to ease transition from  0.94 -> 0.96.
221    * 
222    * @deprecated as of 0.96, use {@link CellUtil#cloneQualifier(Cell)}
223    */
224   @Deprecated
225   byte[] getQualifier();
226 
227   /**
228    * WARNING do not use, expensive.  this gets an arraycopy of the cell's row.
229    *
230    * Added to ease transition from  0.94 -> 0.96.
231    * 
232    * @deprecated as of 0.96, use {@link CellUtil#getRowByte(Cell, int)}
233    */
234   @Deprecated
235   byte[] getRow();
236 }