001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.apache.hadoop.hbase;
020
021import org.apache.yetus.audience.InterfaceAudience;
022
023
024/**
025 * The unit of storage in HBase consisting of the following fields:
026 * <br>
027 * <pre>
028 * 1) row
029 * 2) column family
030 * 3) column qualifier
031 * 4) timestamp
032 * 5) type
033 * 6) MVCC version
034 * 7) value
035 * </pre>
036 * <p>
037 * Uniqueness is determined by the combination of row, column family, column qualifier,
038 * timestamp, and type.
039 * </p>
040 * <p>
041 * The natural comparator will perform a bitwise comparison on row, column family, and column
042 * qualifier. Less intuitively, it will then treat the greater timestamp as the lesser value with
043 * the goal of sorting newer cells first.
044 * </p>
045 * <p>
046 * Cell implements Comparable&lt;Cell&gt; which is only meaningful when
047 * comparing to other keys in the
048 * same table. It uses CellComparator which does not work on the -ROOT- and hbase:meta tables.
049 * </p>
050 * <p>
051 * In the future, we may consider adding a boolean isOnHeap() method and a getValueBuffer() method
052 * that can be used to pass a value directly from an off-heap ByteBuffer to the network without
053 * copying into an on-heap byte[].
054 * </p>
055 * <p>
056 * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as
057 * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate
058 * byte[]'s.
059 * </p>
060 */
061@InterfaceAudience.Public
062public interface Cell {
063
064  //1) Row
065
066  /**
067   * Contiguous raw bytes that may start at any index in the containing array. Max length is
068   * Short.MAX_VALUE which is 32,767 bytes.
069   * @return The array containing the row bytes.
070   */
071  byte[] getRowArray();
072
073  /**
074   * @return Array index of first row byte
075   */
076  int getRowOffset();
077
078  /**
079   * @return Number of row bytes. Must be &lt; rowArray.length - offset.
080   */
081  short getRowLength();
082
083
084  //2) Family
085
086  /**
087   * Contiguous bytes composed of legal HDFS filename characters which may start at any index in the
088   * containing array. Max length is Byte.MAX_VALUE, which is 127 bytes.
089   * @return the array containing the family bytes.
090   */
091  byte[] getFamilyArray();
092
093  /**
094   * @return Array index of first family byte
095   */
096  int getFamilyOffset();
097
098  /**
099   * @return Number of family bytes.  Must be &lt; familyArray.length - offset.
100   */
101  byte getFamilyLength();
102
103
104  //3) Qualifier
105
106  /**
107   * Contiguous raw bytes that may start at any index in the containing array.
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 &lt; 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 0 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   * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Use {@link #getType()}.
137   */
138  @Deprecated
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   * @deprecated As of HBase-2.0. Will be removed in HBase-3.0.
151   */
152  @Deprecated
153  long getSequenceId();
154
155  //7) Value
156
157  /**
158   * Contiguous raw bytes that may start at any index in the containing array. Max length is
159   * Integer.MAX_VALUE which is 2,147,483,647 bytes.
160   * @return The array containing the value bytes.
161   */
162  byte[] getValueArray();
163
164  /**
165   * @return Array index of first value byte
166   */
167  int getValueOffset();
168
169  /**
170   * @return Number of value bytes.  Must be &lt; valueArray.length - offset.
171   */
172  int getValueLength();
173
174  /**
175   * Contiguous raw bytes representing tags that may start at any index in the containing array.
176   * @return the tags byte array
177   * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Tags are are now internal.
178   */
179  @Deprecated
180  byte[] getTagsArray();
181
182  /**
183   * @return the first offset where the tags start in the Cell
184   * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Tags are are now internal.
185   */
186  @Deprecated
187  int getTagsOffset();
188
189  /**
190   * HBase internally uses 2 bytes to store tags length in Cell.
191   * As the tags length is always a non-negative number, to make good use of the sign bit,
192   * the max of tags length is defined 2 * Short.MAX_VALUE + 1 = 65535.
193   * As a result, the return type is int, because a short is not capable of handling that.
194   * Please note that even if the return type is int, the max tags length is far
195   * less than Integer.MAX_VALUE.
196   *
197   * @return the total length of the tags in the Cell.
198   * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Tags are are now internal.
199   */
200  @Deprecated
201  int getTagsLength();
202
203  /**
204   * Returns the type of cell in a human readable format using {@link Type}.
205   * Note : This does not expose the internal types of Cells like {@link KeyValue.Type#Maximum} and
206   * {@link KeyValue.Type#Minimum}
207   * @return The data type this cell: one of Put, Delete, etc
208   */
209  default Type getType() {
210    byte byteType = getTypeByte();
211    Type t = Type.CODE_ARRAY[byteType & 0xff];
212    if (t != null) {
213      return t;
214    }
215    throw new UnsupportedOperationException("Invalid type of cell " + byteType);
216  }
217
218  /**
219   * The valid types for user to build the cell. Currently, This is subset of {@link KeyValue.Type}.
220   */
221  enum Type {
222    Put((byte) 4),
223
224    Delete((byte) 8),
225
226    DeleteFamilyVersion((byte) 10),
227
228    DeleteColumn((byte) 12),
229
230    DeleteFamily((byte) 14);
231
232    private final byte code;
233
234    Type(final byte c) {
235      this.code = c;
236    }
237
238    public byte getCode() {
239      return this.code;
240    }
241
242    private static final Type[] CODE_ARRAY = new Type[256];
243
244    static {
245      for (Type t : Type.values()) {
246        CODE_ARRAY[t.code & 0xff] = t;
247      }
248    }
249  }
250}