lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/TermRangeFilter.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 java.text.Collator;
  21
  22 /**
  23  * A Filter that restricts search results to a range of term
  24  * values in a given field.
  25  *
  26  * <p>This filter matches the documents looking for terms that fall into the
  27  * supplied range according to {@link
  28  * String#compareTo(String)}, unless a <code>Collator</code> is provided. It is not intended
  29  * for numerical ranges; use {@link NumericRangeFilter} instead.
  30  *
  31  * <p>If you construct a large number of range filters with different ranges but on the
  32  * same field, {@link FieldCacheRangeFilter} may have significantly better performance.
  33  * @since 2.9
  34  */
  35 public class TermRangeFilter extends MultiTermQueryWrapperFilter<TermRangeQuery> {
  36
  37   /**
  38    * @param fieldName The field this range applies to
  39    * @param lowerTerm The lower bound on this range
  40    * @param upperTerm The upper bound on this range
  41    * @param includeLower Does this range include the lower bound?
  42    * @param includeUpper Does this range include the upper bound?
  43    * @throws IllegalArgumentException if both terms are null or if
  44    *  lowerTerm is null and includeLower is true (similar for upperTerm
  45    *  and includeUpper)
  46    */
  47   public TermRangeFilter(String fieldName, String lowerTerm, String upperTerm,
  48                      boolean includeLower, boolean includeUpper) {
  49       super(new TermRangeQuery(fieldName, lowerTerm, upperTerm, includeLower, includeUpper));
  50   }
  51
  52   /**
  53    * <strong>WARNING:</strong> Using this constructor and supplying a non-null
  54    * value in the <code>collator</code> parameter will cause every single
  55    * index Term in the Field referenced by lowerTerm and/or upperTerm to be
  56    * examined.  Depending on the number of index Terms in this Field, the
  57    * operation could be very slow.
  58    *
  59    * @param lowerTerm The lower bound on this range
  60    * @param upperTerm The upper bound on this range
  61    * @param includeLower Does this range include the lower bound?
  62    * @param includeUpper Does this range include the upper bound?
  63    * @param collator The collator to use when determining range inclusion; set
  64    *  to null to use Unicode code point ordering instead of collation.
  65    * @throws IllegalArgumentException if both terms are null or if
  66    *  lowerTerm is null and includeLower is true (similar for upperTerm
  67    *  and includeUpper)
  68    */
  69   public TermRangeFilter(String fieldName, String lowerTerm, String upperTerm,
  70                      boolean includeLower, boolean includeUpper,
  71                      Collator collator) {
  72       super(new TermRangeQuery(fieldName, lowerTerm, upperTerm, includeLower, includeUpper, collator));
  73   }
  74
  75   /**
  76    * Constructs a filter for field <code>fieldName</code> matching
  77    * less than or equal to <code>upperTerm</code>.
  78    */
  79   public static TermRangeFilter Less(String fieldName, String upperTerm) {
  80       return new TermRangeFilter(fieldName, null, upperTerm, false, true);
  81   }
  82
  83   /**
  84    * Constructs a filter for field <code>fieldName</code> matching
  85    * greater than or equal to <code>lowerTerm</code>.
  86    */
  87   public static TermRangeFilter More(String fieldName, String lowerTerm) {
  88       return new TermRangeFilter(fieldName, lowerTerm, null, true, false);
  89   }
  90
  91   /** Returns the field name for this filter */
  92   public String getField() { return query.getField(); }
  93
  94   /** Returns the lower value of this range filter */
  95   public String getLowerTerm() { return query.getLowerTerm(); }
  96
  97   /** Returns the upper value of this range filter */
  98   public String getUpperTerm() { return query.getUpperTerm(); }
  99
 100   /** Returns <code>true</code> if the lower endpoint is inclusive */
 101   public boolean includesLower() { return query.includesLower(); }
 102
 103   /** Returns <code>true</code> if the upper endpoint is inclusive */
 104   public boolean includesUpper() { return query.includesUpper(); }
 105
 106   /** Returns the collator used to determine range inclusion, if any. */
 107   public Collator getCollator() { return query.getCollator(); }
 108 }