hbase-common/src/main/java/org/apache/hadoop/hbase/Cell.java

   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.io.HeapSize;
  22 import org.apache.yetus.audience.InterfaceAudience;
  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  * Cell implements Comparable&lt;Cell&gt; which is only meaningful when
  48  * comparing to other keys in the
  49  * same table. It uses CellComparator which does not work on the -ROOT- and hbase:meta tables.
  50  * </p>
  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  * <p>
  57  * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as
  58  * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate
  59  * byte[]'s.
  60  * </p>
  61  */
  62 @InterfaceAudience.Public
  63 public interface Cell extends HeapSize {
  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 &lt; 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 &lt; 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.
 109    * @return The array containing the qualifier bytes.
 110    */
 111   byte[] getQualifierArray();
 112
 113   /**
 114    * @return Array index of first qualifier byte
 115    */
 116   int getQualifierOffset();
 117
 118   /**
 119    * @return Number of qualifier bytes.  Must be &lt; qualifierArray.length - offset.
 120    */
 121   int getQualifierLength();
 122
 123
 124   //4) Timestamp
 125
 126   /**
 127    * @return Long value representing time at which this cell was "Put" into the row.  Typically
 128    * represents the time of insertion, but can be any value from 0 to Long.MAX_VALUE.
 129    */
 130   long getTimestamp();
 131
 132
 133   //5) Type
 134
 135   /**
 136    * @return The byte representation of the KeyValue.TYPE of this cell: one of Put, Delete, etc
 137    * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Use {@link #getType()}.
 138    */
 139   @Deprecated
 140   byte getTypeByte();
 141
 142
 143   //6) SequenceId
 144
 145   /**
 146    * A region-specific unique monotonically increasing sequence ID given to each Cell. It always
 147    * exists for cells in the memstore but is not retained forever. It will be kept for
 148    * {@link HConstants#KEEP_SEQID_PERIOD} days, but generally becomes irrelevant after the cell's
 149    * row is no longer involved in any operations that require strict consistency.
 150    * @return seqId (always &gt; 0 if exists), or 0 if it no longer exists
 151    * @deprecated As of HBase-2.0. Will be removed in HBase-3.0.
 152    */
 153   @Deprecated
 154   long getSequenceId();
 155
 156   //7) Value
 157
 158   /**
 159    * Contiguous raw bytes that may start at any index in the containing array. Max length is
 160    * Integer.MAX_VALUE which is 2,147,483,647 bytes.
 161    * @return The array containing the value bytes.
 162    */
 163   byte[] getValueArray();
 164
 165   /**
 166    * @return Array index of first value byte
 167    */
 168   int getValueOffset();
 169
 170   /**
 171    * @return Number of value bytes.  Must be &lt; valueArray.length - offset.
 172    */
 173   int getValueLength();
 174
 175   /**
 176    * @return Serialized size (defaults to include tag length if has some tags).
 177    */
 178   int getSerializedSize();
 179
 180   /**
 181    * Contiguous raw bytes representing tags that may start at any index in the containing array.
 182    * @return the tags byte array
 183    * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Tags are are now internal.
 184    */
 185   @Deprecated
 186   byte[] getTagsArray();
 187
 188   /**
 189    * @return the first offset where the tags start in the Cell
 190    * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Tags are are now internal.
 191    */
 192   @Deprecated
 193   int getTagsOffset();
 194
 195   /**
 196    * HBase internally uses 2 bytes to store tags length in Cell.
 197    * As the tags length is always a non-negative number, to make good use of the sign bit,
 198    * the max of tags length is defined 2 * Short.MAX_VALUE + 1 = 65535.
 199    * As a result, the return type is int, because a short is not capable of handling that.
 200    * Please note that even if the return type is int, the max tags length is far
 201    * less than Integer.MAX_VALUE.
 202    *
 203    * @return the total length of the tags in the Cell.
 204    * @deprecated As of HBase-2.0. Will be removed in HBase-3.0. Tags are are now internal.
 205    */
 206   @Deprecated
 207   int getTagsLength();
 208
 209   /**
 210    * Returns the type of cell in a human readable format using {@link Type}.
 211    * Note : This does not expose the internal types of Cells like {@link KeyValue.Type#Maximum} and
 212    * {@link KeyValue.Type#Minimum}
 213    * @return The data type this cell: one of Put, Delete, etc
 214    */
 215   default Type getType() {
 216     byte byteType = getTypeByte();
 217     Type t = Type.CODE_ARRAY[byteType & 0xff];
 218     if (t != null) {
 219       return t;
 220     }
 221     throw new UnsupportedOperationException("Invalid type of cell " + byteType);
 222   }
 223
 224   /**
 225    * The valid types for user to build the cell. Currently, This is subset of {@link KeyValue.Type}.
 226    */
 227   enum Type {
 228     Put((byte) 4),
 229
 230     Delete((byte) 8),
 231
 232     DeleteFamilyVersion((byte) 10),
 233
 234     DeleteColumn((byte) 12),
 235
 236     DeleteFamily((byte) 14);
 237
 238     private final byte code;
 239
 240     Type(final byte c) {
 241       this.code = c;
 242     }
 243
 244     public byte getCode() {
 245       return this.code;
 246     }
 247
 248     private static final Type[] CODE_ARRAY = new Type[256];
 249
 250     static {
 251       for (Type t : Type.values()) {
 252         CODE_ARRAY[t.code & 0xff] = t;
 253       }
 254     }
 255   }
 256 }