hbase-common/src/main/java/org/apache/hadoop/hbase/CellComparator.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 import java.util.Comparator;
  22 import org.apache.hadoop.hbase.util.ByteBufferUtils;
  23 import org.apache.yetus.audience.InterfaceAudience;
  24 import org.apache.yetus.audience.InterfaceStability;
  25
  26 /**
  27  * Comparator for comparing cells and has some specialized methods that allows comparing individual
  28  * cell components like row, family, qualifier and timestamp
  29  */
  30 @InterfaceAudience.Public
  31 @InterfaceStability.Evolving
  32 public interface CellComparator extends Comparator<Cell> {
  33   /**
  34    * A comparator for ordering cells in user-space tables. Useful when writing cells in sorted
  35    * order as necessary for bulk import (i.e. via MapReduce).
  36    * <p>
  37    * CAUTION: This comparator may provide inaccurate ordering for cells from system tables,
  38    * and should not be relied upon in that case.
  39    */
  40   // For internal use, see CellComparatorImpl utility methods.
  41   static CellComparator getInstance() {
  42     return CellComparatorImpl.COMPARATOR;
  43   }
  44
  45   /**
  46    * Lexographically compares two cells. The key part of the cell is taken for comparison which
  47    * includes row, family, qualifier, timestamp and type
  48    * @param leftCell the left hand side cell
  49    * @param rightCell the right hand side cell
  50    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
  51    *         cells are equal
  52    */
  53   @Override
  54   int compare(Cell leftCell, Cell rightCell);
  55
  56   /**
  57    * Compare cells.
  58    * @param ignoreSequenceid True if we are to compare the key portion only and ignore
  59    *    the sequenceid. Set to false to compare key and consider sequenceid.
  60    * @return 0 if equal, -1 if a &lt; b, and +1 if a &gt; b.
  61    */
  62   int compare(Cell leftCell, Cell rightCell, boolean ignoreSequenceid);
  63
  64   /**
  65    * Lexographically compares the rows of two cells.
  66    * @param leftCell the left hand side cell
  67    * @param rightCell the right hand side cell
  68    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
  69    *         cells are equal
  70    */
  71   int compareRows(Cell leftCell, Cell rightCell);
  72
  73   /**
  74    * Compares the row part of the cell with a simple plain byte[] like the
  75    * stopRow in Scan.
  76    * @param cell the cell
  77    * @param bytes the byte[] representing the row to be compared with
  78    * @param offset the offset of the byte[]
  79    * @param length the length of the byte[]
  80    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
  81    *         cells are equal
  82    */
  83   int compareRows(Cell cell, byte[] bytes, int offset, int length);
  84
  85   /**
  86    * @param row ByteBuffer that wraps a row; will read from current position and will reading all
  87    *            remaining; will not disturb the ByteBuffer internal state.
  88    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
  89    *         cells are equal
  90    */
  91   default int compareRows(ByteBuffer row, Cell cell) {
  92     if (cell instanceof ByteBufferExtendedCell) {
  93       return ByteBufferUtils.compareTo(row, row.position(), row.remaining(),
  94         ((ByteBufferExtendedCell) cell).getRowByteBuffer(),
  95         ((ByteBufferExtendedCell) cell).getRowPosition(),
  96         cell.getRowLength());
  97     }
  98     return ByteBufferUtils.compareTo(row, row.position(), row.remaining(),
  99       cell.getRowArray(), cell.getRowOffset(),
 100       cell.getRowLength());
 101   }
 102
 103   /**
 104    * Lexographically compares the two cells excluding the row part. It compares family, qualifier,
 105    * timestamp and the type
 106    * @param leftCell the left hand side cell
 107    * @param rightCell the right hand side cell
 108    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
 109    *         cells are equal
 110    */
 111   int compareWithoutRow(Cell leftCell, Cell rightCell);
 112
 113   /**
 114    * Lexographically compares the families of the two cells
 115    * @param leftCell the left hand side cell
 116    * @param rightCell the right hand side cell
 117    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
 118    *         cells are equal
 119    */
 120   int compareFamilies(Cell leftCell, Cell rightCell);
 121
 122   /**
 123    * Lexographically compares the qualifiers of the two cells
 124    * @param leftCell the left hand side cell
 125    * @param rightCell the right hand side cell
 126    * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
 127    *         cells are equal
 128    */
 129   int compareQualifiers(Cell leftCell, Cell rightCell);
 130
 131   /**
 132    * Compares cell's timestamps in DESCENDING order. The below older timestamps sorting ahead of
 133    * newer timestamps looks wrong but it is intentional. This way, newer timestamps are first found
 134    * when we iterate over a memstore and newer versions are the first we trip over when reading from
 135    * a store file.
 136    * @param leftCell the left hand side cell
 137    * @param rightCell the right hand side cell
 138    * @return 1 if left's timestamp &lt; right's timestamp -1 if left's timestamp &gt; right's
 139    *         timestamp 0 if both timestamps are equal
 140    */
 141   int compareTimestamps(Cell leftCell, Cell rightCell);
 142
 143   /**
 144    * Compares cell's timestamps in DESCENDING order. The below older timestamps sorting ahead of
 145    * newer timestamps looks wrong but it is intentional. This way, newer timestamps are first found
 146    * when we iterate over a memstore and newer versions are the first we trip over when reading from
 147    * a store file.
 148    * @param leftCellts the left cell's timestamp
 149    * @param rightCellts the right cell's timestamp
 150    * @return 1 if left's timestamp &lt; right's timestamp -1 if left's timestamp &gt; right's
 151    *         timestamp 0 if both timestamps are equal
 152    */
 153   int compareTimestamps(long leftCellts, long rightCellts);
 154
 155   /**
 156    * @return A dumbed-down, fast comparator for hbase2 base-type, the {@link ByteBufferKeyValue}.
 157    *   Create an instance when you make a new memstore, when you know only BBKVs will be passed.
 158    *   Do not pollute with types other than BBKV if can be helped; the Comparator will slow.
 159    */
 160   Comparator getSimpleComparator();
 161 }