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 java.io.IOException;
021import java.io.OutputStream;
022import java.nio.ByteBuffer;
023import org.apache.hadoop.hbase.io.HeapSize;
024import org.apache.hadoop.hbase.util.ByteBufferUtils;
025import org.apache.yetus.audience.InterfaceAudience;
026
027/**
028 * Extension to {@link Cell} with server side required functions. Server side Cell implementations
029 * must implement this.
030 */
031@InterfaceAudience.Private
032public interface ExtendedCell extends RawCell, HeapSize {
033  int CELL_NOT_BASED_ON_CHUNK = -1;
034
035  /**
036   * Write this cell to an OutputStream in a {@link KeyValue} format. <br>
037   * KeyValue format <br>
038   * <code>&lt;4 bytes keylength&gt; &lt;4 bytes valuelength&gt; &lt;2 bytes rowlength&gt;
039   * &lt;row&gt; &lt;1 byte columnfamilylength&gt; &lt;columnfamily&gt; &lt;columnqualifier&gt;
040   * &lt;8 bytes timestamp&gt; &lt;1 byte keytype&gt; &lt;value&gt; &lt;2 bytes tagslength&gt;
041   * &lt;tags&gt;</code>
042   * @param out      Stream to which cell has to be written
043   * @param withTags Whether to write tags.
044   * @return how many bytes are written.
045   */
046  // TODO remove the boolean param once HBASE-16706 is done.
047  default int write(OutputStream out, boolean withTags) throws IOException {
048    // Key length and then value length
049    ByteBufferUtils.putInt(out, KeyValueUtil.keyLength(this));
050    ByteBufferUtils.putInt(out, getValueLength());
051
052    // Key
053    PrivateCellUtil.writeFlatKey(this, out);
054
055    if (getValueLength() > 0) {
056      // Value
057      out.write(getValueArray(), getValueOffset(), getValueLength());
058    }
059
060    // Tags length and tags byte array
061    if (withTags && getTagsLength() > 0) {
062      // Tags length
063      out.write((byte) (0xff & (getTagsLength() >> 8)));
064      out.write((byte) (0xff & getTagsLength()));
065
066      // Tags byte array
067      out.write(getTagsArray(), getTagsOffset(), getTagsLength());
068    }
069
070    return getSerializedSize(withTags);
071  }
072
073  /**
074   * KeyValue format
075   * <p/>
076   * <code>&lt;4 bytes keylength&gt; &lt;4 bytes valuelength&gt; &lt;2 bytes rowlength&gt;
077   * &lt;row&gt; &lt;1 byte columnfamilylength&gt; &lt;columnfamily&gt; &lt;columnqualifier&gt;
078   * &lt;8 bytes timestamp&gt; &lt;1 byte keytype&gt; &lt;value&gt; &lt;2 bytes tagslength&gt;
079   * &lt;tags&gt;</code>
080   * @param withTags Whether to write tags.
081   * @return Bytes count required to serialize this Cell in a {@link KeyValue} format.
082   */
083  // TODO remove the boolean param once HBASE-16706 is done.
084  default int getSerializedSize(boolean withTags) {
085    return KeyValueUtil.length(getRowLength(), getFamilyLength(), getQualifierLength(),
086      getValueLength(), getTagsLength(), withTags);
087  }
088
089  /** Returns Serialized size (defaults to include tag length). */
090  @Override
091  default int getSerializedSize() {
092    return getSerializedSize(true);
093  }
094
095  /**
096   * Write this Cell into the given buf's offset in a {@link KeyValue} format.
097   * @param buf    The buffer where to write the Cell.
098   * @param offset The offset within buffer, to write the Cell.
099   */
100  default void write(ByteBuffer buf, int offset) {
101    KeyValueUtil.appendTo(this, buf, offset, true);
102  }
103
104  /**
105   * Does a deep copy of the contents to a new memory area and returns it as a new cell.
106   * @return The deep cloned cell
107   */
108  default ExtendedCell deepClone() {
109    // When being added to the memstore, deepClone() is called and KeyValue has less heap overhead.
110    return new KeyValue(this);
111  }
112
113  /**
114   * Extracts the id of the backing bytebuffer of this cell if it was obtained from fixed sized
115   * chunks as in case of MemstoreLAB
116   * @return the chunk id if the cell is backed by fixed sized Chunks, else return
117   *         {@link #CELL_NOT_BASED_ON_CHUNK}; i.e. -1.
118   */
119  default int getChunkId() {
120    return CELL_NOT_BASED_ON_CHUNK;
121  }
122
123  /**
124   * Sets with the given seqId.
125   * @param seqId sequence ID
126   */
127  void setSequenceId(long seqId) throws IOException;
128
129  /**
130   * Sets with the given timestamp.
131   * @param ts timestamp
132   */
133  void setTimestamp(long ts) throws IOException;
134
135  /**
136   * Sets with the given timestamp.
137   * @param ts buffer containing the timestamp value
138   */
139  void setTimestamp(byte[] ts) throws IOException;
140
141  /**
142   * A region-specific unique monotonically increasing sequence ID given to each Cell. It always
143   * exists for cells in the memstore but is not retained forever. It will be kept for
144   * {@link HConstants#KEEP_SEQID_PERIOD} days, but generally becomes irrelevant after the cell's
145   * row is no longer involved in any operations that require strict consistency.
146   * @return seqId (always &gt; 0 if exists), or 0 if it no longer exists
147   */
148  long getSequenceId();
149
150  /**
151   * Contiguous raw bytes representing tags that may start at any index in the containing array.
152   * @return the tags byte array
153   */
154  byte[] getTagsArray();
155
156  /** Returns the first offset where the tags start in the Cell */
157  int getTagsOffset();
158
159  /**
160   * HBase internally uses 2 bytes to store tags length in Cell. As the tags length is always a
161   * non-negative number, to make good use of the sign bit, the max of tags length is defined 2 *
162   * Short.MAX_VALUE + 1 = 65535. As a result, the return type is int, because a short is not
163   * capable of handling that. Please note that even if the return type is int, the max tags length
164   * is far less than Integer.MAX_VALUE.
165   * @return the total length of the tags in the Cell.
166   */
167  int getTagsLength();
168
169  /** Returns The byte representation of the KeyValue.TYPE of this cell: one of Put, Delete, etc */
170  byte getTypeByte();
171}