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