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