lucene-java-3.4.0/lucene/src/java/org/apache/lucene/search/TermRangeQuery.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.io.IOException;
  21 import java.text.Collator;
  22
  23 import org.apache.lucene.index.IndexReader;
  24 import org.apache.lucene.util.ToStringUtils;
  25
  26 /**
  27  * A Query that matches documents within an range of terms.
  28  *
  29  * <p>This query matches the documents looking for terms that fall into the
  30  * supplied range according to {@link
  31  * String#compareTo(String)}, unless a <code>Collator</code> is provided. It is not intended
  32  * for numerical ranges; use {@link NumericRangeQuery} instead.
  33  *
  34  * <p>This query uses the {@link
  35  * MultiTermQuery#CONSTANT_SCORE_AUTO_REWRITE_DEFAULT}
  36  * rewrite method.
  37  * @since 2.9
  38  */
  39
  40 public class TermRangeQuery extends MultiTermQuery {
  41   private String lowerTerm;
  42   private String upperTerm;
  43   private Collator collator;
  44   private String field;
  45   private boolean includeLower;
  46   private boolean includeUpper;
  47
  48
  49   /**
  50    * Constructs a query selecting all terms greater/equal than <code>lowerTerm</code>
  51    * but less/equal than <code>upperTerm</code>.
  52    *
  53    * <p>
  54    * If an endpoint is null, it is said
  55    * to be "open". Either or both endpoints may be open.  Open endpoints may not
  56    * be exclusive (you can't select all but the first or last term without
  57    * explicitly specifying the term to exclude.)
  58    *
  59    * @param field The field that holds both lower and upper terms.
  60    * @param lowerTerm
  61    *          The term text at the lower end of the range
  62    * @param upperTerm
  63    *          The term text at the upper end of the range
  64    * @param includeLower
  65    *          If true, the <code>lowerTerm</code> is
  66    *          included in the range.
  67    * @param includeUpper
  68    *          If true, the <code>upperTerm</code> is
  69    *          included in the range.
  70    */
  71   public TermRangeQuery(String field, String lowerTerm, String upperTerm, boolean includeLower, boolean includeUpper) {
  72     this(field, lowerTerm, upperTerm, includeLower, includeUpper, null);
  73   }
  74
  75   /** Constructs a query selecting all terms greater/equal than
  76    * <code>lowerTerm</code> but less/equal than <code>upperTerm</code>.
  77    * <p>
  78    * If an endpoint is null, it is said
  79    * to be "open". Either or both endpoints may be open.  Open endpoints may not
  80    * be exclusive (you can't select all but the first or last term without
  81    * explicitly specifying the term to exclude.)
  82    * <p>
  83    * If <code>collator</code> is not null, it will be used to decide whether
  84    * index terms are within the given range, rather than using the Unicode code
  85    * point order in which index terms are stored.
  86    * <p>
  87    * <strong>WARNING:</strong> Using this constructor and supplying a non-null
  88    * value in the <code>collator</code> parameter will cause every single
  89    * index Term in the Field referenced by lowerTerm and/or upperTerm to be
  90    * examined.  Depending on the number of index Terms in this Field, the
  91    * operation could be very slow.
  92    *
  93    * @param lowerTerm The Term text at the lower end of the range
  94    * @param upperTerm The Term text at the upper end of the range
  95    * @param includeLower
  96    *          If true, the <code>lowerTerm</code> is
  97    *          included in the range.
  98    * @param includeUpper
  99    *          If true, the <code>upperTerm</code> is
 100    *          included in the range.
 101    * @param collator The collator to use to collate index Terms, to determine
 102    *  their membership in the range bounded by <code>lowerTerm</code> and
 103    *  <code>upperTerm</code>.
 104    */
 105   public TermRangeQuery(String field, String lowerTerm, String upperTerm, boolean includeLower, boolean includeUpper,
 106                     Collator collator) {
 107     this.field = field;
 108     this.lowerTerm = lowerTerm;
 109     this.upperTerm = upperTerm;
 110     this.includeLower = includeLower;
 111     this.includeUpper = includeUpper;
 112     this.collator = collator;
 113   }
 114
 115   /** Returns the field name for this query */
 116   public String getField() { return field; }
 117
 118   /** Returns the lower value of this range query */
 119   public String getLowerTerm() { return lowerTerm; }
 120
 121   /** Returns the upper value of this range query */
 122   public String getUpperTerm() { return upperTerm; }
 123
 124   /** Returns <code>true</code> if the lower endpoint is inclusive */
 125   public boolean includesLower() { return includeLower; }
 126
 127   /** Returns <code>true</code> if the upper endpoint is inclusive */
 128   public boolean includesUpper() { return includeUpper; }
 129
 130   /** Returns the collator used to determine range inclusion, if any. */
 131   public Collator getCollator() { return collator; }
 132
 133   @Override
 134   protected FilteredTermEnum getEnum(IndexReader reader) throws IOException {
 135     return new TermRangeTermEnum(reader, field, lowerTerm,
 136         upperTerm, includeLower, includeUpper, collator);
 137   }
 138
 139   /** Prints a user-readable version of this query. */
 140   @Override
 141   public String toString(String field) {
 142       StringBuilder buffer = new StringBuilder();
 143       if (!getField().equals(field)) {
 144           buffer.append(getField());
 145           buffer.append(":");
 146       }
 147       buffer.append(includeLower ? '[' : '{');
 148       buffer.append(lowerTerm != null ? lowerTerm : "*");
 149       buffer.append(" TO ");
 150       buffer.append(upperTerm != null ? upperTerm : "*");
 151       buffer.append(includeUpper ? ']' : '}');
 152       buffer.append(ToStringUtils.boost(getBoost()));
 153       return buffer.toString();
 154   }
 155
 156   @Override
 157   public int hashCode() {
 158     final int prime = 31;
 159     int result = super.hashCode();
 160     result = prime * result + ((collator == null) ? 0 : collator.hashCode());
 161     result = prime * result + ((field == null) ? 0 : field.hashCode());
 162     result = prime * result + (includeLower ? 1231 : 1237);
 163     result = prime * result + (includeUpper ? 1231 : 1237);
 164     result = prime * result + ((lowerTerm == null) ? 0 : lowerTerm.hashCode());
 165     result = prime * result + ((upperTerm == null) ? 0 : upperTerm.hashCode());
 166     return result;
 167   }
 168
 169   @Override
 170   public boolean equals(Object obj) {
 171     if (this == obj)
 172       return true;
 173     if (!super.equals(obj))
 174       return false;
 175     if (getClass() != obj.getClass())
 176       return false;
 177     TermRangeQuery other = (TermRangeQuery) obj;
 178     if (collator == null) {
 179       if (other.collator != null)
 180         return false;
 181     } else if (!collator.equals(other.collator))
 182       return false;
 183     if (field == null) {
 184       if (other.field != null)
 185         return false;
 186     } else if (!field.equals(other.field))
 187       return false;
 188     if (includeLower != other.includeLower)
 189       return false;
 190     if (includeUpper != other.includeUpper)
 191       return false;
 192     if (lowerTerm == null) {
 193       if (other.lowerTerm != null)
 194         return false;
 195     } else if (!lowerTerm.equals(other.lowerTerm))
 196       return false;
 197     if (upperTerm == null) {
 198       if (other.upperTerm != null)
 199         return false;
 200     } else if (!upperTerm.equals(other.upperTerm))
 201       return false;
 202     return true;
 203   }
 204
 205 }