lucene/codecs/src/java/org/apache/lucene/codecs/uniformsplit/IndexDictionary.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.lucene.codecs.uniformsplit;

import java.io.IOException;
import org.apache.lucene.store.DataOutput;
import org.apache.lucene.util.Accountable;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.IOSupplier;

/**
 * Immutable stateless index dictionary kept in RAM.
 *
 * <p>Implementations must be immutable.
 *
 * <p>Use {@link IndexDictionary.Builder} to build the {@link IndexDictionary}.
 *
 * <p>Create a stateful {@link IndexDictionary.Browser} to seek a term in this {@link
 * IndexDictionary} and get its corresponding block file pointer to the terms block file.
 *
 * <p>There is a single implementation of this interface, {@link FSTDictionary}. However this
 * interface allows you to plug easily a new kind of index dictionary to experiment and improve the
 * existing one.
 *
 * @lucene.experimental
 */
public interface IndexDictionary extends Accountable {

  /**
   * Writes this dictionary to the provided output.
   *
   * @param blockEncoder The {@link BlockEncoder} for specific encoding of this index dictionary; or
   *     null if none.
   */
  void write(DataOutput output, BlockEncoder blockEncoder) throws IOException;

  /** Creates a new {@link IndexDictionary.Browser}. */
  Browser browser() throws IOException;

  /** Builds an immutable {@link IndexDictionary}. */
  interface Builder {

    /**
     * Adds a [block key - block file pointer] entry to the dictionary.
     *
     * <p>The Uniform Split technique adds block keys in the dictionary. See {@link BlockReader} and
     * {@link TermBytes} for more info about block key and minimal distinguishing prefix (MDP).
     *
     * <p>All block keys are added in strictly increasing order of the block file pointers, this
     * allows long encoding optimizations such as with {@link
     * org.apache.lucene.util.fst.PositiveIntOutputs} for {@link org.apache.lucene.util.fst.FST}.
     *
     * @param blockKey The block key which is the minimal distinguishing prefix (MDP) of the first
     *     term of a block.
     * @param blockFilePointer Non-negative file pointer to the start of the block in the block
     *     file.
     */
    void add(BytesRef blockKey, long blockFilePointer) throws IOException;

    /** Builds the immutable {@link IndexDictionary} for the added entries. */
    IndexDictionary build() throws IOException;
  }

  /**
   * Stateful {@link IndexDictionary.Browser} to seek a term in this {@link IndexDictionary} and get
   * its corresponding block file pointer in the block file.
   */
  interface Browser {

    /**
     * Seeks the given term in the {@link IndexDictionary} and returns its corresponding block file
     * pointer.
     *
     * @return The block file pointer corresponding to the term if it matches exactly a block key in
     *     the dictionary. Otherwise the floor block key, which is the greatest block key present in
     *     the dictionary that is alphabetically preceding the searched term. Otherwise {@code -1}
     *     if there is no floor block key because the searched term precedes alphabetically the
     *     first block key of the dictionary.
     */
    long seekBlock(BytesRef term) throws IOException;
  }

  /**
   * Supplier for a new stateful {@link Browser} created on the immutable {@link IndexDictionary}.
   *
   * <p>The immutable {@link IndexDictionary} is lazy loaded thread safely. This lazy loading allows
   * us to load it only when {@link org.apache.lucene.index.TermsEnum#seekCeil} or {@link
   * org.apache.lucene.index.TermsEnum#seekExact} are called (it is not loaded for a direct
   * all-terms enumeration).
   */
  interface BrowserSupplier extends IOSupplier<Browser>, Accountable {}
}