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.Serializable;
021import java.nio.ByteBuffer;
022import java.util.Comparator;
023import org.apache.hadoop.hbase.util.ByteBufferUtils;
024import org.apache.hadoop.hbase.util.Bytes;
025import org.apache.yetus.audience.InterfaceAudience;
026import org.apache.yetus.audience.InterfaceStability;
027
028/**
029 * Comparator for comparing cells and has some specialized methods that allows comparing individual
030 * cell components like row, family, qualifier and timestamp
031 */
032@InterfaceAudience.Public
033@InterfaceStability.Evolving
034public interface CellComparator extends Comparator<Cell>, Serializable {
035  /**
036   * A comparator for ordering cells in user-space tables. Useful when writing cells in sorted order
037   * as necessary for bulk import (i.e. via MapReduce).
038   * <p>
039   * CAUTION: This comparator may provide inaccurate ordering for cells from system tables, and
040   * should not be relied upon in that case.
041   */
042  // For internal use, see CellComparatorImpl utility methods.
043  static CellComparator getInstance() {
044    return CellComparatorImpl.COMPARATOR;
045  }
046
047  /**
048   * Lexographically compares two cells. The key part of the cell is taken for comparison which
049   * includes row, family, qualifier, timestamp and type
050   * @param leftCell  the left hand side cell
051   * @param rightCell the right hand side cell
052   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
053   *         cells are equal
054   */
055  @Override
056  int compare(Cell leftCell, Cell rightCell);
057
058  /**
059   * Compare cells.
060   * @param ignoreSequenceid True if we are to compare the key portion only and ignore the
061   *                         sequenceid. Set to false to compare key and consider sequenceid.
062   * @return 0 if equal, -1 if a &lt; b, and +1 if a &gt; b.
063   */
064  int compare(Cell leftCell, Cell rightCell, boolean ignoreSequenceid);
065
066  /**
067   * Lexographically compares the rows of two cells.
068   * @param leftCell  the left hand side cell
069   * @param rightCell the right hand side cell
070   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
071   *         cells are equal
072   */
073  int compareRows(Cell leftCell, Cell rightCell);
074
075  /**
076   * Compares the row part of the cell with a simple plain byte[] like the stopRow in Scan.
077   * @param cell   the cell
078   * @param bytes  the byte[] representing the row to be compared with
079   * @param offset the offset of the byte[]
080   * @param length the length of the byte[]
081   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
082   *         cells are equal
083   */
084  int compareRows(Cell cell, byte[] bytes, int offset, int length);
085
086  /**
087   * Compares two row bytes
088   * @param leftRow  the byte array of the left row
089   * @param rightRow the byte array of the right row
090   * @return greater than 0 if leftRow is bigger, less than 0 if rightRow is bigger, 0 if both rows
091   *         are equal
092   */
093  default int compareRows(byte[] leftRow, byte[] rightRow) {
094    return Bytes.compareTo(leftRow, rightRow);
095  }
096
097  /**
098   * Lexicographically compare two rows
099   * @param row ByteBuffer that wraps a row; will read from current position and will reading all
100   *            remaining; will not disturb the ByteBuffer internal state.
101   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
102   *         cells are equal
103   */
104  default int compareRows(ByteBuffer row, Cell cell) {
105    if (cell instanceof ByteBufferExtendedCell) {
106      return ByteBufferUtils.compareTo(row, row.position(), row.remaining(),
107        ((ByteBufferExtendedCell) cell).getRowByteBuffer(),
108        ((ByteBufferExtendedCell) cell).getRowPosition(), cell.getRowLength());
109    }
110    return ByteBufferUtils.compareTo(row, row.position(), row.remaining(), cell.getRowArray(),
111      cell.getRowOffset(), cell.getRowLength());
112  }
113
114  /**
115   * Lexicographically compares the two cells excluding the row part. It compares family, qualifier,
116   * timestamp and the type
117   * @param leftCell  the left hand side cell
118   * @param rightCell the right hand side cell
119   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
120   *         cells are equal
121   */
122  int compareWithoutRow(Cell leftCell, Cell rightCell);
123
124  /**
125   * Lexicographically compares the families of the two cells
126   * @param leftCell  the left hand side cell
127   * @param rightCell the right hand side cell
128   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
129   *         cells are equal
130   */
131  int compareFamilies(Cell leftCell, Cell rightCell);
132
133  /**
134   * Lexicographically compares the qualifiers of the two cells
135   * @param leftCell  the left hand side cell
136   * @param rightCell the right hand side cell
137   * @return greater than 0 if leftCell is bigger, less than 0 if rightCell is bigger, 0 if both
138   *         cells are equal
139   */
140  int compareQualifiers(Cell leftCell, Cell rightCell);
141
142  /**
143   * Compares cell's timestamps in DESCENDING order. The below older timestamps sorting ahead of
144   * newer timestamps looks wrong but it is intentional. This way, newer timestamps are first found
145   * when we iterate over a memstore and newer versions are the first we trip over when reading from
146   * a store file.
147   * @param leftCell  the left hand side cell
148   * @param rightCell the right hand side cell
149   * @return 1 if left's timestamp &lt; right's timestamp -1 if left's timestamp &gt; right's
150   *         timestamp 0 if both timestamps are equal
151   */
152  int compareTimestamps(Cell leftCell, Cell rightCell);
153
154  /**
155   * Compares cell's timestamps in DESCENDING order. The below older timestamps sorting ahead of
156   * newer timestamps looks wrong but it is intentional. This way, newer timestamps are first found
157   * when we iterate over a memstore and newer versions are the first we trip over when reading from
158   * a store file.
159   * @param leftCellts  the left cell's timestamp
160   * @param rightCellts the right cell's timestamp
161   * @return 1 if left's timestamp &lt; right's timestamp -1 if left's timestamp &gt; right's
162   *         timestamp 0 if both timestamps are equal
163   */
164  int compareTimestamps(long leftCellts, long rightCellts);
165
166  /**
167   * Return a dumbed-down, fast comparator for hbase2 base-type, the {@link ByteBufferKeyValue}.
168   * Create an instance when you make a new memstore, when you know only BBKVs will be passed. Do
169   * not pollute with types other than BBKV if can be helped; the Comparator will slow.
170   */
171  Comparator<Cell> getSimpleComparator();
172}