ceph/src/arrow/java/algorithm/src/main/java/org/apache/arrow/algorithm/dictionary/DictionaryBuilder.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (the "License"); you may not use this file except in compliance with
   7  * the License.  You may obtain a copy of the License at
   8  *
   9  *    http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 package org.apache.arrow.algorithm.dictionary;
  19
  20 import org.apache.arrow.vector.ValueVector;
  21
  22 /**
  23  * A dictionary builder is intended for the scenario frequently encountered in practice:
  24  * the dictionary is not known a priori, so it is generated dynamically.
  25  * In particular, when a new value arrives, it is tested to check if it is already
  26  * in the dictionary. If so, it is simply neglected, otherwise, it is added to the dictionary.
  27  * <p>
  28  *   The dictionary builder is intended to build a single dictionary.
  29  *   So it cannot be used for different dictionaries.
  30  * </p>
  31  * <p>Below gives the sample code for using the dictionary builder
  32  * <pre>{@code
  33  * DictionaryBuilder dictionaryBuilder = ...
  34  * ...
  35  * dictionaryBuild.addValue(newValue);
  36  * ...
  37  * }</pre>
  38  * </p>
  39  * <p>
  40  *   With the above code, the dictionary vector will be populated,
  41  *   and it can be retrieved by the {@link DictionaryBuilder#getDictionary()} method.
  42  *   After that, dictionary encoding can proceed with the populated dictionary..
  43  * </p>
  44  *
  45  * @param <V> the dictionary vector type.
  46  */
  47 public interface DictionaryBuilder<V extends ValueVector> {
  48
  49   /**
  50    * Try to add all values from the target vector to the dictionary.
  51    *
  52    * @param targetVector the target vector containing values to probe.
  53    * @return the number of values actually added to the dictionary.
  54    */
  55   int addValues(V targetVector);
  56
  57   /**
  58    * Try to add an element from the target vector to the dictionary.
  59    *
  60    * @param targetVector the target vector containing new element.
  61    * @param targetIndex  the index of the new element in the target vector.
  62    * @return the index of the new element in the dictionary.
  63    */
  64   int addValue(V targetVector, int targetIndex);
  65
  66   /**
  67    * Gets the dictionary built.
  68    *
  69    * @return the dictionary.
  70    */
  71   V getDictionary();
  72 }