hbase-common/src/main/java/org/apache/hadoop/hbase/ByteBufferExtendedCell.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 package org.apache.hadoop.hbase;
  19
  20 import java.nio.ByteBuffer;
  21
  22 import org.apache.yetus.audience.InterfaceAudience;
  23
  24 /**
  25  * This class is a server side extension to the {@link Cell} interface. It is used when the
  26  * Cell is backed by a {@link ByteBuffer}: i.e. <code>cell instanceof ByteBufferedCell</code>.
  27  *
  28  * <p>This class has getters for the row, column family, column qualifier, value and tags hosting
  29  * ByteBuffers. It also has getters of the *position* within a ByteBuffer where these
  30  * field bytes begin. These are needed because a single ByteBuffer may back one or many Cell
  31  * instances -- it depends on the implementation -- so the ByteBuffer position as returned by
  32  * {@link ByteBuffer#arrayOffset()} cannot be relied upon. Also, do not confuse these position
  33  * methods with the getXXXOffset methods from the super Interface, {@link Cell}; dependent up on
  34  * implementation, the Cell getXXXOffset methods can return the same value as a call to its
  35  * equivalent position method from below BUT they can also stray; if a ByteBufferedCell, use the
  36  * below position methods to find where a field begins.
  37  *
  38  * <p>Use the getXXXLength methods from Cell to find a fields length.
  39  *
  40  * <p>A Cell object can be of this type only on the server side.
  41  *
  42  * <p>WARNING: If a Cell is backed by an offheap ByteBuffer, any call to getXXXArray() will result
  43  * in a temporary byte array creation and a bytes copy. Avoid these allocations by using the
  44  * appropriate Cell access server-side: i.e. ByteBufferedCell when backed by a ByteBuffer and Cell
  45  * when it is not.
  46  */
  47 /*
  48  * Even though all the methods are abstract, ByteBufferExtendedCell is not made to be an interface
  49  * with intent. In CellComparator compare method, we have instance of check to decide whether to
  50  * use getXXXArray() or getXXXByteBuffer(). This is a very hot method in read and write paths.
  51  * if (left instanceof ByteBufferExtendedCell && right instanceof ByteBufferExtendedCell) {
  52       ....
  53     }
  54     if (left instanceof ByteBufferExtendedCell) {
  55       ....
  56     }
  57     if (right instanceof ByteBufferExtendedCell) {
  58       ....
  59     }
  60     return Bytes.compareTo(left.getRowArray(), left.getRowOffset(), left.getRowLength(),
  61         right.getRowArray(), right.getRowOffset(), right.getRowLength());
  62  * We did JMH micro benchmark tests with both left and right cells as ByteBufferExtendedCell, one
  63  * only ByteBufferExtendedCell and both as Cells. This is compared against JMH results on compare
  64  * logic with out any instance of checks. We noticed that if ByteBufferExtendedCell is an
  65  * interface, the benchmark result seems to be very bad for case of both right and left are Cell
  66  * only (Not ByteBufferExtendedCell). When ByteBufferExtendedCell is an abstract class all 4
  67  * possible cases giving almost similar performance number compared with compare logic with no
  68  * instance of checks.
  69  */
  70 @InterfaceAudience.Private
  71 public abstract class ByteBufferExtendedCell implements ExtendedCell {
  72   /**
  73    * @return The {@link ByteBuffer} containing the row bytes.
  74    */
  75   public abstract ByteBuffer getRowByteBuffer();
  76
  77   /**
  78    * @return Position in the {@link ByteBuffer} where row bytes start
  79    */
  80   public abstract int getRowPosition();
  81
  82   /**
  83    * @return The {@link ByteBuffer} containing the column family bytes.
  84    */
  85   public abstract ByteBuffer getFamilyByteBuffer();
  86
  87   /**
  88    * @return Position in the {@link ByteBuffer} where column family bytes start
  89    */
  90   public abstract int getFamilyPosition();
  91
  92   /**
  93    * @return The {@link ByteBuffer} containing the column qualifier bytes.
  94    */
  95   public abstract ByteBuffer getQualifierByteBuffer();
  96
  97   /**
  98    * @return Position in the {@link ByteBuffer} where column qualifier bytes start
  99    */
 100   public abstract int getQualifierPosition();
 101
 102   /**
 103    * @return The {@link ByteBuffer} containing the value bytes.
 104    */
 105   public abstract ByteBuffer getValueByteBuffer();
 106
 107   /**
 108    * @return Position in the {@link ByteBuffer} where value bytes start
 109    */
 110   public abstract int getValuePosition();
 111
 112   /**
 113    * @return The {@link ByteBuffer} containing the tag bytes.
 114    */
 115   public abstract ByteBuffer getTagsByteBuffer();
 116
 117   /**
 118    * @return Position in the {@link ByteBuffer} where tag bytes start
 119    */
 120   public abstract int getTagsPosition();
 121 }