lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/NumericRangeFilter.java

   1 package org.apache.lucene.search;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 import org.apache.lucene.analysis.NumericTokenStream; // for javadocs
  21 import org.apache.lucene.document.NumericField; // for javadocs
  22 import org.apache.lucene.util.NumericUtils; // for javadocs
  23
  24 /**
  25  * A {@link Filter} that only accepts numeric values within
  26  * a specified range. To use this, you must first index the
  27  * numeric values using {@link NumericField} (expert: {@link
  28  * NumericTokenStream}).
  29  *
  30  * <p>You create a new NumericRangeFilter with the static
  31  * factory methods, eg:
  32  *
  33  * <pre>
  34  * Filter f = NumericRangeFilter.newFloatRange("weight", 0.03f, 0.10f, true, true);
  35  * </pre>
  36  *
  37  * accepts all documents whose float valued "weight" field
  38  * ranges from 0.03 to 0.10, inclusive.
  39  * See {@link NumericRangeQuery} for details on how Lucene
  40  * indexes and searches numeric valued fields.
  41  *
  42  * @since 2.9
  43  **/
  44 public final class NumericRangeFilter<T extends Number> extends MultiTermQueryWrapperFilter<NumericRangeQuery<T>> {
  45
  46   private NumericRangeFilter(final NumericRangeQuery<T> query) {
  47     super(query);
  48   }
  49
  50   /**
  51    * Factory that creates a <code>NumericRangeFilter</code>, that filters a <code>long</code>
  52    * range using the given <a href="NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>.
  53    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
  54    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
  55    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
  56    */
  57   public static NumericRangeFilter<Long> newLongRange(final String field, final int precisionStep,
  58     Long min, Long max, final boolean minInclusive, final boolean maxInclusive
  59   ) {
  60     return new NumericRangeFilter<Long>(
  61       NumericRangeQuery.newLongRange(field, precisionStep, min, max, minInclusive, maxInclusive)
  62     );
  63   }
  64
  65   /**
  66    * Factory that creates a <code>NumericRangeFilter</code>, that queries a <code>long</code>
  67    * range using the default <code>precisionStep</code> {@link NumericUtils#PRECISION_STEP_DEFAULT} (4).
  68    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
  69    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
  70    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
  71    */
  72   public static NumericRangeFilter<Long> newLongRange(final String field,
  73     Long min, Long max, final boolean minInclusive, final boolean maxInclusive
  74   ) {
  75     return new NumericRangeFilter<Long>(
  76       NumericRangeQuery.newLongRange(field, min, max, minInclusive, maxInclusive)
  77     );
  78   }
  79
  80   /**
  81    * Factory that creates a <code>NumericRangeFilter</code>, that filters a <code>int</code>
  82    * range using the given <a href="NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>.
  83    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
  84    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
  85    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
  86    */
  87   public static NumericRangeFilter<Integer> newIntRange(final String field, final int precisionStep,
  88     Integer min, Integer max, final boolean minInclusive, final boolean maxInclusive
  89   ) {
  90     return new NumericRangeFilter<Integer>(
  91       NumericRangeQuery.newIntRange(field, precisionStep, min, max, minInclusive, maxInclusive)
  92     );
  93   }
  94
  95   /**
  96    * Factory that creates a <code>NumericRangeFilter</code>, that queries a <code>int</code>
  97    * range using the default <code>precisionStep</code> {@link NumericUtils#PRECISION_STEP_DEFAULT} (4).
  98    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
  99    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
 100    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 101    */
 102   public static NumericRangeFilter<Integer> newIntRange(final String field,
 103     Integer min, Integer max, final boolean minInclusive, final boolean maxInclusive
 104   ) {
 105     return new NumericRangeFilter<Integer>(
 106       NumericRangeQuery.newIntRange(field, min, max, minInclusive, maxInclusive)
 107     );
 108   }
 109
 110   /**
 111    * Factory that creates a <code>NumericRangeFilter</code>, that filters a <code>double</code>
 112    * range using the given <a href="NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>.
 113    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 114    * by setting the min or max value to <code>null</code>.
 115    * {@link Double#NaN} will never match a half-open range, to hit {@code NaN} use a query
 116    * with {@code min == max == Double.NaN}. By setting inclusive to false, it will
 117    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 118    */
 119   public static NumericRangeFilter<Double> newDoubleRange(final String field, final int precisionStep,
 120     Double min, Double max, final boolean minInclusive, final boolean maxInclusive
 121   ) {
 122     return new NumericRangeFilter<Double>(
 123       NumericRangeQuery.newDoubleRange(field, precisionStep, min, max, minInclusive, maxInclusive)
 124     );
 125   }
 126
 127   /**
 128    * Factory that creates a <code>NumericRangeFilter</code>, that queries a <code>double</code>
 129    * range using the default <code>precisionStep</code> {@link NumericUtils#PRECISION_STEP_DEFAULT} (4).
 130    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 131    * by setting the min or max value to <code>null</code>.
 132    * {@link Double#NaN} will never match a half-open range, to hit {@code NaN} use a query
 133    * with {@code min == max == Double.NaN}. By setting inclusive to false, it will
 134    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 135    */
 136   public static NumericRangeFilter<Double> newDoubleRange(final String field,
 137     Double min, Double max, final boolean minInclusive, final boolean maxInclusive
 138   ) {
 139     return new NumericRangeFilter<Double>(
 140       NumericRangeQuery.newDoubleRange(field, min, max, minInclusive, maxInclusive)
 141     );
 142   }
 143
 144   /**
 145    * Factory that creates a <code>NumericRangeFilter</code>, that filters a <code>float</code>
 146    * range using the given <a href="NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>.
 147    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 148    * by setting the min or max value to <code>null</code>.
 149    * {@link Float#NaN} will never match a half-open range, to hit {@code NaN} use a query
 150    * with {@code min == max == Float.NaN}. By setting inclusive to false, it will
 151    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 152    */
 153   public static NumericRangeFilter<Float> newFloatRange(final String field, final int precisionStep,
 154     Float min, Float max, final boolean minInclusive, final boolean maxInclusive
 155   ) {
 156     return new NumericRangeFilter<Float>(
 157       NumericRangeQuery.newFloatRange(field, precisionStep, min, max, minInclusive, maxInclusive)
 158     );
 159   }
 160
 161   /**
 162    * Factory that creates a <code>NumericRangeFilter</code>, that queries a <code>float</code>
 163    * range using the default <code>precisionStep</code> {@link NumericUtils#PRECISION_STEP_DEFAULT} (4).
 164    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 165    * by setting the min or max value to <code>null</code>.
 166    * {@link Float#NaN} will never match a half-open range, to hit {@code NaN} use a query
 167    * with {@code min == max == Float.NaN}. By setting inclusive to false, it will
 168    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 169    */
 170   public static NumericRangeFilter<Float> newFloatRange(final String field,
 171     Float min, Float max, final boolean minInclusive, final boolean maxInclusive
 172   ) {
 173     return new NumericRangeFilter<Float>(
 174       NumericRangeQuery.newFloatRange(field, min, max, minInclusive, maxInclusive)
 175     );
 176   }
 177
 178   /** Returns the field name for this filter */
 179   public String getField() { return query.getField(); }
 180
 181   /** Returns <code>true</code> if the lower endpoint is inclusive */
 182   public boolean includesMin() { return query.includesMin(); }
 183
 184   /** Returns <code>true</code> if the upper endpoint is inclusive */
 185   public boolean includesMax() { return query.includesMax(); }
 186
 187   /** Returns the lower value of this range filter */
 188   public T getMin() { return query.getMin(); }
 189
 190   /** Returns the upper value of this range filter */
 191   public T getMax() { return query.getMax(); }
 192
 193   /** Returns the precision step. */
 194   public int getPrecisionStep() { return query.getPrecisionStep(); }
 195
 196 }