lucene-java-3.4.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>. By setting inclusive to false, it will
 115    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 116    */
 117   public static NumericRangeFilter<Double> newDoubleRange(final String field, final int precisionStep,
 118     Double min, Double max, final boolean minInclusive, final boolean maxInclusive
 119   ) {
 120     return new NumericRangeFilter<Double>(
 121       NumericRangeQuery.newDoubleRange(field, precisionStep, min, max, minInclusive, maxInclusive)
 122     );
 123   }
 124
 125   /**
 126    * Factory that creates a <code>NumericRangeFilter</code>, that queries a <code>double</code>
 127    * range using the default <code>precisionStep</code> {@link NumericUtils#PRECISION_STEP_DEFAULT} (4).
 128    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 129    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
 130    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 131    */
 132   public static NumericRangeFilter<Double> newDoubleRange(final String field,
 133     Double min, Double max, final boolean minInclusive, final boolean maxInclusive
 134   ) {
 135     return new NumericRangeFilter<Double>(
 136       NumericRangeQuery.newDoubleRange(field, min, max, minInclusive, maxInclusive)
 137     );
 138   }
 139
 140   /**
 141    * Factory that creates a <code>NumericRangeFilter</code>, that filters a <code>float</code>
 142    * range using the given <a href="NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>.
 143    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 144    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
 145    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 146    */
 147   public static NumericRangeFilter<Float> newFloatRange(final String field, final int precisionStep,
 148     Float min, Float max, final boolean minInclusive, final boolean maxInclusive
 149   ) {
 150     return new NumericRangeFilter<Float>(
 151       NumericRangeQuery.newFloatRange(field, precisionStep, min, max, minInclusive, maxInclusive)
 152     );
 153   }
 154
 155   /**
 156    * Factory that creates a <code>NumericRangeFilter</code>, that queries a <code>float</code>
 157    * range using the default <code>precisionStep</code> {@link NumericUtils#PRECISION_STEP_DEFAULT} (4).
 158    * You can have half-open ranges (which are in fact &lt;/&le; or &gt;/&ge; queries)
 159    * by setting the min or max value to <code>null</code>. By setting inclusive to false, it will
 160    * match all documents excluding the bounds, with inclusive on, the boundaries are hits, too.
 161    */
 162   public static NumericRangeFilter<Float> newFloatRange(final String field,
 163     Float min, Float max, final boolean minInclusive, final boolean maxInclusive
 164   ) {
 165     return new NumericRangeFilter<Float>(
 166       NumericRangeQuery.newFloatRange(field, min, max, minInclusive, maxInclusive)
 167     );
 168   }
 169
 170   /** Returns the field name for this filter */
 171   public String getField() { return query.getField(); }
 172
 173   /** Returns <code>true</code> if the lower endpoint is inclusive */
 174   public boolean includesMin() { return query.includesMin(); }
 175
 176   /** Returns <code>true</code> if the upper endpoint is inclusive */
 177   public boolean includesMax() { return query.includesMax(); }
 178
 179   /** Returns the lower value of this range filter */
 180   public T getMin() { return query.getMin(); }
 181
 182   /** Returns the upper value of this range filter */
 183   public T getMax() { return query.getMax(); }
 184
 185   /** Returns the precision step. */
 186   public int getPrecisionStep() { return query.getPrecisionStep(); }
 187
 188 }