lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Doug Cutting <cutt...@apache.org>
Subject Re: API cleanup: BooleanQuery.add()
Date Fri, 20 Aug 2004 21:48:01 GMT
I still prefer Occur.MUST, Occur.SHOULD and Occur.MUST_NOT. 
BooleanQuery is really a misnomer, since it is not the traditional tree 
of boolean operators.  Rather it is designed to directly support the 
plus and minus operators popularized by web search engines.  (It also, 
  felicitously, naturallly permits some bitmask-based optimizations that 
would be considerably more complicated using a traditional boolean 
operator tree.)

These operators are often and accurately described as affecting whether 
terms must occur, should occur or must not occur.  AND, OR and NOT are 
confusing, since their boolean semantics are not the same as their 
English semantics.  Also, Lucene's prohibited is really AND_NOT, not 
NOT.  Such things are frequently a source of confusion from folks trying 
to translate a traditional boolean query tree to a Lucene BooleanQuery. 
  I'd rather make it clearer that this is not a traditional boolean 
query, but rather a different way to achieve the same ends.

Doug

Daniel Naber wrote:
> BooleanQuery.add() currently takes two boolean values. That's difficult to 
> use as these two parameters can easily be confused. Also, there's a 
> runtime error if one uses true for both parameters. Thus this method's API 
> should be redesigned. It has been discussed here already:
> 
> http://www.mail-archive.com/lucene-user%40jakarta.apache.org/msg08479.html
> 
> I suggest the attached patch. Instead of Doug's suggestion of "Occur" my 
> patch uses "Operator" and instead of MUST/MUST_NOT/SHOULD it uses 
> AND/NOT/OR for the enumeration. I think SHOULD would be difficult to 
> understand, but I'm not happy with OR either. The problem is that it's 
> okay to have a BooleanQuery with only one Term, and OR would mean the same 
> as AND in that case.
> 
> Please post your suggestions for better names.
> 
> Regards
>  Daniel
> 
> 
> 
> ------------------------------------------------------------------------
> 
> Index: BooleanQuery.java
> ===================================================================
> RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/search/BooleanQuery.java,v
> retrieving revision 1.24
> diff -u -r1.24 BooleanQuery.java
> --- BooleanQuery.java	14 May 2004 12:56:29 -0000	1.24
> +++ BooleanQuery.java	17 Aug 2004 22:20:47 -0000
> @@ -25,6 +25,33 @@
>    */
>  public class BooleanQuery extends Query {
>  
> +  public static final class Operator {
> +    
> +    private String name;
> +    
> +    private Operator() {
> +      // typesafe enum pattern, no public constructor
> +    }
> +    
> +    private Operator(String name) {
> +      // typesafe enum pattern, no public constructor
> +      this.name = name;
> +    }
> +    
> +    public String toString() {
> +      return name;
> +    }
> +
> +    /** Use this operator for terms that <i>must</i> appear in the matching
document. */
> +    public static final Operator AND = new Operator("AND");
> +    /** Use this operator for terms of which at least one <i>must</i> appear
in the 
> +     * matching document. */
> +    public static final Operator OR = new Operator("OR");
> +    /** Use this operator for terms that <i>must not</i> appear in the matching
document. */
> +    public static final Operator NOT = new Operator("NOT");
> +    
> +  }
> +  
>    /**
>     * Default value is 1024.  Use <code>org.apache.lucene.maxClauseCount</code>
>     * system property to override.
> @@ -65,14 +92,31 @@
>     * It is an error to specify a clause as both <code>required</code> and
>     * <code>prohibited</code>.
>     *
> -   * @see #getMaxClauseCount()
> +   * @deprecated use {@link #add(Query, Operator)} instead
>     */
>    public void add(Query query, boolean required, boolean prohibited) {
>      add(new BooleanClause(query, required, prohibited));
>    }
>  
>    /** Adds a clause to a boolean query.
> -    * @see #getMaxClauseCount()
> +   *
> +   * @throws TooManyClauses if the new number of clauses exceeds the maximum clause
number
> +   * @see #getMaxClauseCount()
> +   */
> +  public void add(Query query, Operator operator) {
> +    if (operator == Operator.AND)
> +      add(new BooleanClause(query, true, false));
> +    else if (operator == Operator.OR)
> +      add(new BooleanClause(query, false, false));
> +    else if (operator == Operator.NOT)
> +      add(new BooleanClause(query, false, true));
> +    else
> +      throw new IllegalArgumentException("Unknown operator " + operator);
> +  }
> +
> +  /** Adds a clause to a boolean query.
> +   * @throws TooManyClauses if the new number of clauses exceeds the maximum clause
number
> +   * @see #getMaxClauseCount()
>     */
>    public void add(BooleanClause clause) {
>      if (clauses.size() >= maxClauseCount)
> 
> 
> 
> ------------------------------------------------------------------------
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: lucene-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: lucene-dev-help@jakarta.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: lucene-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: lucene-dev-help@jakarta.apache.org


Mime
View raw message