1   package org.apache.lucene.index;
    2   
    3   import org.apache.lucene.util.StringHelper;
    4   
    5   /**
    6    * Licensed to the Apache Software Foundation (ASF) under one or more
    7    * contributor license agreements.  See the NOTICE file distributed with
    8    * this work for additional information regarding copyright ownership.
    9    * The ASF licenses this file to You under the Apache License, Version 2.0
   10    * (the "License"); you may not use this file except in compliance with
   11    * the License.  You may obtain a copy of the License at
   12    *
   13    *     http://www.apache.org/licenses/LICENSE-2.0
   14    *
   15    * Unless required by applicable law or agreed to in writing, software
   16    * distributed under the License is distributed on an "AS IS" BASIS,
   17    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   18    * See the License for the specific language governing permissions and
   19    * limitations under the License.
   20    */
   21   
   22   /**
   23     A Term represents a word from text.  This is the unit of search.  It is
   24     composed of two elements, the text of the word, as a string, and the name of
   25     the field that the text occurred in, an interned string.
   26   
   27     Note that terms may represent more than words from text fields, but also
   28     things like dates, email addresses, urls, etc.  */
   29   
   30   public final class Term implements Comparable<Term>, java.io.Serializable {
   31     String field;
   32     String text;
   33   
   34     /** Constructs a Term with the given field and text.
   35      * <p>Note that a null field or null text value results in undefined
   36      * behavior for most Lucene APIs that accept a Term parameter. */
   37     public Term(String fld, String txt) {
   38       field = StringHelper.intern(fld);
   39       text = txt;
   40     }
   41   
   42     /** Constructs a Term with the given field and empty text.
   43      * This serves two purposes: 1) reuse of a Term with the same field.
   44      * 2) pattern for a query.
   45      * 
   46      * @param fld
   47      */
   48     public Term(String fld) {
   49       this(fld, "", true);
   50     }
   51   
   52     Term(String fld, String txt, boolean intern) {
   53       field = intern ? StringHelper.intern(fld) : fld;	  // field names are interned
   54       text = txt;					          // unless already known to be
   55     }
   56   
   57     /** Returns the field of this term, an interned string.   The field indicates
   58       the part of a document which this term came from. */
   59     public final String field() { return field; }
   60   
   61     /** Returns the text of this term.  In the case of words, this is simply the
   62       text of the word.  In the case of dates and other types, this is an
   63       encoding of the object as a string.  */
   64     public final String text() { return text; }
   65     
   66     /**
   67      * Optimized construction of new Terms by reusing same field as this Term
   68      * - avoids field.intern() overhead 
   69      * @param text The text of the new term (field is implicitly same as this Term instance)
   70      * @return A new Term
   71      */
   72     public Term createTerm(String text)
   73     {
   74         return new Term(field,text,false);
   75     }
   76   
   77     @Override
   78     public boolean equals(Object obj) {
   79       if (this == obj)
   80         return true;
   81       if (obj == null)
   82         return false;
   83       if (getClass() != obj.getClass())
   84         return false;
   85       Term other = (Term) obj;
   86       if (field == null) {
   87         if (other.field != null)
   88           return false;
   89       } else if (!field.equals(other.field))
   90         return false;
   91       if (text == null) {
   92         if (other.text != null)
   93           return false;
   94       } else if (!text.equals(other.text))
   95         return false;
   96       return true;
   97     }
   98   
   99     @Override
  100     public int hashCode() {
  101       final int prime = 31;
  102       int result = 1;
  103       result = prime * result + ((field == null) ? 0 : field.hashCode());
  104       result = prime * result + ((text == null) ? 0 : text.hashCode());
  105       return result;
  106     }
  107   
  108     /** Compares two terms, returning a negative integer if this
  109       term belongs before the argument, zero if this term is equal to the
  110       argument, and a positive integer if this term belongs after the argument.
  111   
  112       The ordering of terms is first by field, then by text.*/
  113     public final int compareTo(Term other) {
  114       if (field == other.field)			  // fields are interned
  115         return text.compareTo(other.text);
  116       else
  117         return field.compareTo(other.field);
  118     }
  119   
  120     /** Resets the field and text of a Term. */
  121     final void set(String fld, String txt) {
  122       field = fld;
  123       text = txt;
  124     }
  125   
  126     @Override
  127     public final String toString() { return field + ":" + text; }
  128   
  129     private void readObject(java.io.ObjectInputStream in)
  130       throws java.io.IOException, ClassNotFoundException
  131     {
  132         in.defaultReadObject();
  133         field = StringHelper.intern(field);
  134     }
  135   }