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 */
018package org.apache.hadoop.hbase;
019
020import org.apache.hadoop.hbase.io.HeapSize;
021import org.apache.yetus.audience.InterfaceAudience;
022
023/**
024 * The unit of storage in HBase consisting of the following fields: <br>
025 *
026 * <pre>
027 * 1) row
028 * 2) column family
029 * 3) column qualifier
030 * 4) timestamp
031 * 5) type
032 * 6) MVCC version
033 * 7) value
034 * </pre>
035 * <p>
036 * Uniqueness is determined by the combination of row, column family, column qualifier, timestamp,
037 * and type.
038 * </p>
039 * <p>
040 * The natural comparator will perform a bitwise comparison on row, column family, and column
041 * qualifier. Less intuitively, it will then treat the greater timestamp as the lesser value with
042 * the goal of sorting newer cells first.
043 * </p>
044 * <p>
045 * Cell implements Comparable&lt;Cell&gt; which is only meaningful when comparing to other keys in
046 * the same table. It uses CellComparator which does not work on the -ROOT- and hbase:meta tables.
047 * </p>
048 * <p>
049 * In the future, we may consider adding a boolean isOnHeap() method and a getValueBuffer() method
050 * that can be used to pass a value directly from an off-heap ByteBuffer to the network without
051 * copying into an on-heap byte[].
052 * </p>
053 * <p>
054 * Historic note: the original Cell implementation (KeyValue) requires that all fields be encoded as
055 * consecutive bytes in the same byte[], whereas this interface allows fields to reside in separate
056 * byte[]'s.
057 * </p>
058 */
059@InterfaceAudience.Public
060public interface Cell extends HeapSize {
061
062  // 1) Row
063
064  /**
065   * Contiguous raw bytes that may start at any index in the containing array. Max length is
066   * Short.MAX_VALUE which is 32,767 bytes.
067   * @return The array containing the row bytes.
068   */
069  byte[] getRowArray();
070
071  /** Returns Array index of first row byte */
072  int getRowOffset();
073
074  /** Returns Number of row bytes. Must be &lt; rowArray.length - offset. */
075  short getRowLength();
076
077  // 2) Family
078
079  /**
080   * Contiguous bytes composed of legal HDFS filename characters which may start at any index in the
081   * containing array. Max length is Byte.MAX_VALUE, which is 127 bytes.
082   * @return the array containing the family bytes.
083   */
084  byte[] getFamilyArray();
085
086  /** Returns Array index of first family byte */
087  int getFamilyOffset();
088
089  /** Returns Number of family bytes. Must be &lt; familyArray.length - offset. */
090  byte getFamilyLength();
091
092  // 3) Qualifier
093
094  /**
095   * Contiguous raw bytes that may start at any index in the containing array.
096   * @return The array containing the qualifier bytes.
097   */
098  byte[] getQualifierArray();
099
100  /** Returns Array index of first qualifier byte */
101  int getQualifierOffset();
102
103  /** Returns Number of qualifier bytes. Must be &lt; qualifierArray.length - offset. */
104  int getQualifierLength();
105
106  // 4) Timestamp
107
108  /**
109   * Return a long value representing time at which this cell was "Put" into the row. Typically
110   * represents the time of insertion, but can be any value from 0 to Long.MAX_VALUE.
111   */
112  long getTimestamp();
113
114  // 5) Type
115
116  /**
117   * Returns the type of cell in a human readable format using {@link Type}.
118   * <p>
119   * Note : This does not expose the internal types of Cells like {@link KeyValue.Type#Maximum} and
120   * {@link KeyValue.Type#Minimum}
121   * @return The data type this cell: one of Put, Delete, etc
122   */
123  Type getType();
124
125  // 6) Value
126
127  /**
128   * Contiguous raw bytes that may start at any index in the containing array. Max length is
129   * Integer.MAX_VALUE which is 2,147,483,647 bytes.
130   * @return The array containing the value bytes.
131   */
132  byte[] getValueArray();
133
134  /** Returns Array index of first value byte */
135  int getValueOffset();
136
137  /** Returns Number of value bytes. Must be &lt; valueArray.length - offset. */
138  int getValueLength();
139
140  /** Returns Serialized size (defaults to include tag length if has some tags). */
141  int getSerializedSize();
142
143  /**
144   * The valid types for user to build the cell. Currently, This is subset of {@link KeyValue.Type}.
145   */
146  enum Type {
147    Put((byte) 4),
148
149    Delete((byte) 8),
150
151    DeleteFamilyVersion((byte) 10),
152
153    DeleteColumn((byte) 12),
154
155    DeleteFamily((byte) 14);
156
157    private final byte code;
158
159    Type(final byte c) {
160      this.code = c;
161    }
162
163    public byte getCode() {
164      return this.code;
165    }
166  }
167}