content: package org.apache.lucene.search;
  
  /**
   * Licensed to the Apache Software Foundation (ASF) under one or more
   * contributor license agreements.  See the NOTICE file distributed with
   * this work for additional information regarding copyright ownership.
   * The ASF licenses this file to You under the Apache License, Version 2.0
   * (the "License"); you may not use this file except in compliance with
   * the License.  You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  import java.io.IOException;
  import java.io.Serializable;
  
  import org.apache.lucene.index.IndexReader;
  import org.apache.lucene.index.Term;
  
  import org.apache.lucene.queryParser.QueryParser; // for javadoc
  
  /**
   * An abstract {@link Query} that matches documents
   * containing a subset of terms provided by a {@link
   * FilteredTermEnum} enumeration.
   *
   * <p>This query cannot be used directly; you must subclass
   * it and define {@link #getEnum} to provide a {@link
   * FilteredTermEnum} that iterates through the terms to be
   * matched.
   *
   * <p><b>NOTE</b>: if {@link #setRewriteMethod} is either
   * {@link #CONSTANT_SCORE_BOOLEAN_QUERY_REWRITE} or {@link
   * #SCORING_BOOLEAN_QUERY_REWRITE}, you may encounter a
   * {@link BooleanQuery.TooManyClauses} exception during
   * searching, which happens when the number of terms to be
   * searched exceeds {@link
   * BooleanQuery#getMaxClauseCount()}.  Setting {@link
   * #setRewriteMethod} to {@link #CONSTANT_SCORE_FILTER_REWRITE}
   * prevents this.
   *
   * <p>The recommended rewrite method is {@link
   * #CONSTANT_SCORE_AUTO_REWRITE_DEFAULT}: it doesn't spend CPU
   * computing unhelpful scores, and it tries to pick the most
   * performant rewrite method given the query. If you
   * need scoring (like {@link FuzzyQuery}, use
   * {@link TopTermsScoringBooleanQueryRewrite} which uses
   * a priority queue to only collect competitive terms
   * and not hit this limitation.
   *
   * Note that {@link QueryParser} produces
   * MultiTermQueries using {@link
   * #CONSTANT_SCORE_AUTO_REWRITE_DEFAULT} by default.
   */
  public abstract class MultiTermQuery extends Query {
    protected RewriteMethod rewriteMethod = CONSTANT_SCORE_AUTO_REWRITE_DEFAULT;
    transient int numberOfTerms = 0;
  
    /** Abstract class that defines how the query is rewritten. */
    public static abstract class RewriteMethod implements Serializable {
      public abstract Query rewrite(IndexReader reader, MultiTermQuery query) throws IOException;
    }
  
    /** A rewrite method that first creates a private Filter,
     *  by visiting each term in sequence and marking all docs
     *  for that term.  Matching documents are assigned a
     *  constant score equal to the query's boost.
     * 
     *  <p> This method is faster than the BooleanQuery
     *  rewrite methods when the number of matched terms or
     *  matched documents is non-trivial. Also, it will never
     *  hit an errant {@link BooleanQuery.TooManyClauses}
     *  exception.
     *
     *  @see #setRewriteMethod */
    public static final RewriteMethod CONSTANT_SCORE_FILTER_REWRITE = new RewriteMethod() {
      @Override
      public Query rewrite(IndexReader reader, MultiTermQuery query) {
        Query result = new ConstantScoreQuery(new MultiTermQueryWrapperFilter<MultiTermQuery>(query));
        result.setBoost(query.getBoost());
        return result;
      }
  
      // Make sure we are still a singleton even after deserializing
      protected Object readResolve() {
        return CONSTANT_SCORE_FILTER_REWRITE;
      }
    };
  
    /** A rewrite method that first translates each term into
     *  {@link BooleanClause.Occur#SHOULD} clause in a
     *  BooleanQuery, and keeps the scores as computed by the
     *  query.  Note that typically such scores are
     *  meaningless to the user, and require non-trivial CPU
     *  to compute, so it's almost always better to use {@link
     *  #CONSTANT_SCORE_AUTO_REWRITE_DEFAULT} instead.
     *
     *  <p><b>NOTE</b>: This rewrite method will hit {@link
     *  BooleanQuery.TooManyClauses} if the number of terms
     *  exceeds {@link BooleanQuery#getMaxClauseCount}.
     *
     *  @see #setRewriteMethod */
    public final static RewriteMethod SCORING_BOOLEAN_QUERY_REWRITE = ScoringRewrite.SCORING_BOOLEAN_QUERY_REWRITE;
    
    /** Like {@link #SCORING_BOOLEAN_QUERY_REWRITE} except
     *  scores are not computed.  Instead, each matching
     *  document receives a constant score equal to the
     *  query's boost.
     * 
     *  <p><b>NOTE</b>: This rewrite method will hit {@link
     *  BooleanQuery.TooManyClauses} if the number of terms
     *  exceeds {@link BooleanQuery#getMaxClauseCount}.
     *
     *  @see #setRewriteMethod */
    public final static RewriteMethod CONSTANT_SCORE_BOOLEAN_QUERY_REWRITE = ScoringRewrite.CONSTANT_SCORE_BOOLEAN_QUERY_REWRITE;
  
    /**
     * A rewrite method that first translates each term into
     * {@link BooleanClause.Occur#SHOULD} clause in a BooleanQuery, and keeps the
     * scores as computed by the query.
     * 
     * <p>
     * This rewrite method only uses the top scoring terms so it will not overflow
     * the boolean max clause count. It is the default rewrite method for
     * {@link FuzzyQuery}.
     * 
     * @see #setRewriteMethod
     */
    public static final class TopTermsScoringBooleanQueryRewrite extends TopTermsRewrite<BooleanQuery> {
  
      /** 
       * Create a TopTermsScoringBooleanQueryRewrite for 
       * at most <code>size</code> terms.
       * <p>
       * NOTE: if {@link BooleanQuery#getMaxClauseCount} is smaller than 
       * <code>size</code>, then it will be used instead. 
       */
      public TopTermsScoringBooleanQueryRewrite(int size) {
        super(size);
      }
      
      @Override
      protected int getMaxSize() {
        return BooleanQuery.getMaxClauseCount();
      }
      
      @Override
      protected BooleanQuery getTopLevelQuery() {
        return new BooleanQuery(true);
      }
      
      @Override
      protected void addClause(BooleanQuery topLevel, Term term, float boost) {
        final TermQuery tq = new TermQuery(term);
        tq.setBoost(boost);
        topLevel.add(tq, BooleanClause.Occur.SHOULD);
      }
    }
    
    /**
     * A rewrite method that first translates each term into
     * {@link BooleanClause.Occur#SHOULD} clause in a BooleanQuery, but the scores
     * are only computed as the boost.
     * <p>
     * This rewrite method only uses the top scoring terms so it will not overflow
     * the boolean max clause count.
     * 
     * @see #setRewriteMethod
     */
    public static final class TopTermsBoostOnlyBooleanQueryRewrite extends TopTermsRewrite<BooleanQuery> {
      
      /** 
       * Create a TopTermsBoostOnlyBooleanQueryRewrite for 
       * at most <code>size</code> terms.
       * <p>
       * NOTE: if {@link BooleanQuery#getMaxClauseCount} is smaller than 
       * <code>size</code>, then it will be used instead. 
       */
      public TopTermsBoostOnlyBooleanQueryRewrite(int size) {
        super(size);
      }
      
      @Override
      protected int getMaxSize() {
        return BooleanQuery.getMaxClauseCount();
      }
      
      @Override
      protected BooleanQuery getTopLevelQuery() {
        return new BooleanQuery(true);
      }
      
      @Override
      protected void addClause(BooleanQuery topLevel, Term term, float boost) {
        final Query q = new ConstantScoreQuery(new TermQuery(term));
        q.setBoost(boost);
        topLevel.add(q, BooleanClause.Occur.SHOULD);
      }
    }
      
    /** A rewrite method that tries to pick the best
     *  constant-score rewrite method based on term and
     *  document counts from the query.  If both the number of
     *  terms and documents is small enough, then {@link
     *  #CONSTANT_SCORE_BOOLEAN_QUERY_REWRITE} is used.
     *  Otherwise, {@link #CONSTANT_SCORE_FILTER_REWRITE} is
     *  used.
     */
    public static class ConstantScoreAutoRewrite extends org.apache.lucene.search.ConstantScoreAutoRewrite {}
  
    /** Read-only default instance of {@link
     *  ConstantScoreAutoRewrite}, with {@link
     *  ConstantScoreAutoRewrite#setTermCountCutoff} set to
     *  {@link
     *  ConstantScoreAutoRewrite#DEFAULT_TERM_COUNT_CUTOFF}
     *  and {@link
     *  ConstantScoreAutoRewrite#setDocCountPercent} set to
     *  {@link
     *  ConstantScoreAutoRewrite#DEFAULT_DOC_COUNT_PERCENT}.
     *  Note that you cannot alter the configuration of this
     *  instance; you'll need to create a private instance
     *  instead. */
    public final static RewriteMethod CONSTANT_SCORE_AUTO_REWRITE_DEFAULT = new ConstantScoreAutoRewrite() {
      @Override
      public void setTermCountCutoff(int count) {
        throw new UnsupportedOperationException("Please create a private instance");
      }
  
      @Override
      public void setDocCountPercent(double percent) {
        throw new UnsupportedOperationException("Please create a private instance");
      }
  
      // Make sure we are still a singleton even after deserializing
      protected Object readResolve() {
        return CONSTANT_SCORE_AUTO_REWRITE_DEFAULT;
      }
    };
  
    /**
     * Constructs a query matching terms that cannot be represented with a single
     * Term.
     */
    public MultiTermQuery() {
    }
  
    /** Construct the enumeration to be used, expanding the pattern term. */
    protected abstract FilteredTermEnum getEnum(IndexReader reader)
        throws IOException;
  
    /**
     * Expert: Return the number of unique terms visited during execution of the query.
     * If there are many of them, you may consider using another query type
     * or reduce your total term count in index.
     * <p>This method is not thread safe, be sure to only call it when no query is running!
     * If you re-use the same query instance for another
     * search, be sure to first reset the term counter
     * with {@link #clearTotalNumberOfTerms}.
     * <p>On single-segment indexes / no MultiReaders, you get the correct number of
     * unique terms for the whole index. Use this number to compare different queries.
     * For multi-segment indexes this number can also be achieved in
     * non-constant-score mode. In constant-score mode you get the total number of
     * terms seeked for all segments / sub-readers.
     * @see #clearTotalNumberOfTerms
     * @deprecated Don't use this method, as its not thread safe and useless.
     */
    @Deprecated
    public int getTotalNumberOfTerms() {
      return numberOfTerms;
    }
    
    /**
     * Expert: Resets the counting of unique terms.
     * Do this before executing the query/filter.
     * @see #getTotalNumberOfTerms
     * @deprecated Don't use this method, as its not thread safe and useless.
     */
    @Deprecated
    public void clearTotalNumberOfTerms() {
      numberOfTerms = 0;
    }
    
    /** 
     * @deprecated Don't use this method, as its not thread safe and useless.
     */
    @Deprecated
    protected void incTotalNumberOfTerms(int inc) {
      numberOfTerms += inc;
    }
  
    /**
     * To rewrite to a simpler form, instead return a simpler
     * enum from {@link #getEnum(IndexReader)}.  For example,
     * to rewrite to a single term, return a {@link SingleTermEnum}
     */
    @Override
    public final Query rewrite(IndexReader reader) throws IOException {
      return rewriteMethod.rewrite(reader, this);
    }
  
    /**
     * @see #setRewriteMethod
     */
    public RewriteMethod getRewriteMethod() {
      return rewriteMethod;
    }
  
    /**
     * Sets the rewrite method to be used when executing the
     * query.  You can use one of the four core methods, or
     * implement your own subclass of {@link RewriteMethod}. */
    public void setRewriteMethod(RewriteMethod method) {
      rewriteMethod = method;
    }
  
    @Override
    public int hashCode() {
      final int prime = 31;
      int result = 1;
      result = prime * result + Float.floatToIntBits(getBoost());
      result = prime * result;
      result += rewriteMethod.hashCode();
      return result;
    }
  
    @Override
    public boolean equals(Object obj) {
      if (this == obj)
        return true;
      if (obj == null)
        return false;
      if (getClass() != obj.getClass())
        return false;
      MultiTermQuery other = (MultiTermQuery) obj;
      if (Float.floatToIntBits(getBoost()) != Float.floatToIntBits(other.getBoost()))
        return false;
      if (!rewriteMethod.equals(other.rewriteMethod)) {
        return false;
      }
      return true;
    }
   
  }
  