1 package org.apache.lucene.search;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
20 import java.io.IOException;
21 import java.text.Collator;
23 import org.apache.lucene.index.IndexReader;
24 import org.apache.lucene.util.ToStringUtils;
27 * A Query that matches documents within an range of terms.
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.
34 * <p>This query uses the {@link
35 * MultiTermQuery#CONSTANT_SCORE_AUTO_REWRITE_DEFAULT}
40 public class TermRangeQuery extends MultiTermQuery {
41 private String lowerTerm;
42 private String upperTerm;
43 private Collator collator;
45 private boolean includeLower;
46 private boolean includeUpper;
50 * Constructs a query selecting all terms greater/equal than <code>lowerTerm</code>
51 * but less/equal than <code>upperTerm</code>.
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.)
59 * @param field The field that holds both lower and upper terms.
61 * The term text at the lower end of the range
63 * The term text at the upper end of the range
65 * If true, the <code>lowerTerm</code> is
66 * included in the range.
68 * If true, the <code>upperTerm</code> is
69 * included in the range.
71 public TermRangeQuery(String field, String lowerTerm, String upperTerm, boolean includeLower, boolean includeUpper) {
72 this(field, lowerTerm, upperTerm, includeLower, includeUpper, null);
75 /** Constructs a query selecting all terms greater/equal than
76 * <code>lowerTerm</code> but less/equal than <code>upperTerm</code>.
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.)
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.
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.
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
96 * If true, the <code>lowerTerm</code> is
97 * included in the range.
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>.
105 public TermRangeQuery(String field, String lowerTerm, String upperTerm, boolean includeLower, boolean includeUpper,
108 this.lowerTerm = lowerTerm;
109 this.upperTerm = upperTerm;
110 this.includeLower = includeLower;
111 this.includeUpper = includeUpper;
112 this.collator = collator;
115 /** Returns the field name for this query */
116 public String getField() { return field; }
118 /** Returns the lower value of this range query */
119 public String getLowerTerm() { return lowerTerm; }
121 /** Returns the upper value of this range query */
122 public String getUpperTerm() { return upperTerm; }
124 /** Returns <code>true</code> if the lower endpoint is inclusive */
125 public boolean includesLower() { return includeLower; }
127 /** Returns <code>true</code> if the upper endpoint is inclusive */
128 public boolean includesUpper() { return includeUpper; }
130 /** Returns the collator used to determine range inclusion, if any. */
131 public Collator getCollator() { return collator; }
134 protected FilteredTermEnum getEnum(IndexReader reader) throws IOException {
135 return new TermRangeTermEnum(reader, field, lowerTerm,
136 upperTerm, includeLower, includeUpper, collator);
139 /** Prints a user-readable version of this query. */
141 public String toString(String field) {
142 StringBuilder buffer = new StringBuilder();
143 if (!getField().equals(field)) {
144 buffer.append(getField());
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();
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());
170 public boolean equals(Object obj) {
173 if (!super.equals(obj))
175 if (getClass() != obj.getClass())
177 TermRangeQuery other = (TermRangeQuery) obj;
178 if (collator == null) {
179 if (other.collator != null)
181 } else if (!collator.equals(other.collator))
184 if (other.field != null)
186 } else if (!field.equals(other.field))
188 if (includeLower != other.includeLower)
190 if (includeUpper != other.includeUpper)
192 if (lowerTerm == null) {
193 if (other.lowerTerm != null)
195 } else if (!lowerTerm.equals(other.lowerTerm))
197 if (upperTerm == null) {
198 if (other.upperTerm != null)
200 } else if (!upperTerm.equals(other.upperTerm))