001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2007-2007 Pentaho
008// All Rights Reserved.
009*/
010package mondrian.rolap;
011
012import mondrian.rolap.sql.SqlQuery;
013
014import java.util.List;
015
016/**
017 * Condition which constrains a set of values of a single
018 * {@link mondrian.rolap.RolapStar.Column} or a set of columns.
019 *
020 * <p>For example, the predicate
021 * <code>Range([Time].[1997].[Q3], [Time].[1998].[Q2])</code>
022 * constrains the <code>year</code> and <code>quarter</code> columns:
023 *
024 * <blockquote><code>
025 * &nbsp;&nbsp;((year = 1997 and quarter >= 'Q3')<br/>
026 * &nbsp;&nbsp;&nbsp;&nbsp;or (year > 1997))<br/>
027 * and ((year = 1998 and quarter <= 'Q2')<br/>
028 * &nbsp;&nbsp;&nbsp;&nbsp;or (year < 1998))</code></blockquote>
029 *
030 * @author jhyde
031  * @since Jan 15, 2007
032 */
033public interface StarPredicate {
034    /**
035     * Returns a list of constrained columns.
036     *
037     * @return List of constrained columns
038     */
039    public List<RolapStar.Column> getConstrainedColumnList();
040
041    /**
042     * Returns a bitmap of constrained columns to speed up comparison
043     * @return bitmap representing all constraining columns.
044     */
045    public BitKey getConstrainedColumnBitKey();
046
047    /**
048     * Appends a description of this predicate to a <code>StringBuilder</code>.
049     * For example:<ul>
050     * <li>=any</li>
051     * <li>=5</li>
052     * <li>in (2, 4, 6)</li>
053     * </ul>
054     *
055     * @param buf Builder to append to
056     */
057    public abstract void describe(StringBuilder buf);
058
059    /**
060     * Evaluates a constraint against a list of values.
061     *
062     * <p>If one of the values is {@link #WILDCARD}, returns true if constraint is
063     * true for all possible values of that column.
064     *
065     * @param valueList List of values, one for each constrained column
066     * @return Whether constraint holds for given set of values
067     */
068    public boolean evaluate(List<Object> valueList);
069
070    /**
071     * Returns whether this Predicate has the same constraining effect as the
072     * other constraint. This is weaker than {@link Object#equals(Object)}: it
073     * is possible for two different members to constrain the same column in the
074     * same way.
075     *
076     * @param that Other predicate
077     * @return whether the other predicate is equivalent
078     */
079    boolean equalConstraint(StarPredicate that);
080
081    /**
082     * Returns the logical inverse of this Predicate. The result is a Predicate
083     * which holds whenever this predicate holds but the other does not.
084     *
085     * @pre predicate != null
086     * @param predicate Predicate
087     * @return Combined predicate
088     */
089    StarPredicate minus(StarPredicate predicate);
090
091    /**
092     * Returns this union of this Predicate with another. The result is a
093     * Predicate which holds whenever either predicate holds.
094     *
095     * @pre predicate != null
096     * @param predicate Predicate
097     * @return Combined predicate
098     */
099    StarPredicate or(StarPredicate predicate);
100
101    /**
102     * Returns this intersection of this Predicate with another. The result is a
103     * Predicate which holds whenever both predicates hold.
104     *
105     * @pre predicate != null
106     * @param predicate Predicate
107     * @return Combined predicate
108     */
109    StarPredicate and(StarPredicate predicate);
110
111    /**
112     * Wildcard value for {@link #evaluate(java.util.List)}.
113     */
114    Object WILDCARD = new Object();
115
116    void toSql(SqlQuery sqlQuery, StringBuilder buf);
117}
118
119// End StarPredicate.java