001/*
002// $Id: Selection.java 482 2012-01-05 23:27:27Z jhyde $
003//
004// Licensed to Julian Hyde under one or more contributor license
005// agreements. See the NOTICE file distributed with this work for
006// additional information regarding copyright ownership.
007//
008// Julian Hyde licenses this file to you under the Apache License,
009// Version 2.0 (the "License"); you may not use this file except in
010// compliance with the License. You may obtain a copy of the License at:
011//
012// http://www.apache.org/licenses/LICENSE-2.0
013//
014// Unless required by applicable law or agreed to in writing, software
015// distributed under the License is distributed on an "AS IS" BASIS,
016// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017// See the License for the specific language governing permissions and
018// limitations under the License.
019*/
020package org.olap4j.query;
021
022import org.olap4j.mdx.ParseTreeNode;
023import org.olap4j.metadata.Dimension;
024import org.olap4j.metadata.MetadataElement;
025
026import java.util.List;
027
028/**
029 * A selection of members from an OLAP dimension hierarchy. The selection
030 * is a conceptual list of members from a given hierarchy. Once a selection
031 * object is created, one can decide to include or exclude this selection
032 * of members from the resulting query.
033 *
034 * <p>Concrete subclasses of this represent a real selection.
035 * Selections include things such as 'children of', 'siblings of',
036 * 'descendents of' etc.
037 *
038 * <p>This class is different from a {@link org.olap4j.metadata.Member} because it represents an
039 * abstract member selection (e.g. children of widget' that may not represent
040 * any members whereas a Member represents a single member that is known to
041 * exist.
042 *
043 * @author jdixon, jhyde, Luc Boudreau
044 * @version $Id: Selection.java 482 2012-01-05 23:27:27Z jhyde $
045 * @since May 30, 2007
046 */
047public interface Selection extends QueryNode {
048
049    /**
050     * Unique name of the selection root.
051     * @return The unique OLAP name of the selection root.
052     */
053    String getUniqueName();
054
055    /**
056     * Visitor pattern-like function to convert
057     * the selection into a ParseTreeNode. Typical
058     * implementation should be:<br/>
059     * <code>Olap4jNodeConverter.toOlap4j(member, operator);</code>
060     * @return A parse tree node of the selection.
061     */
062    ParseTreeNode visit();
063
064    /**
065     * Parent Dimension of the root selection element.
066     * @return A dimension object.
067     */
068    Dimension getDimension();
069
070    /**
071     * Returns the root selection element of this selection.
072     * @return The root metadata object.
073     */
074    MetadataElement getRootElement();
075
076    /**
077     * The selection context includes selections from other dimensions that
078     * help determine the entire context of a selection, so drill down is
079     * possible.
080     *
081     * @return list of selections
082     */
083    List<Selection> getSelectionContext();
084
085    void addContext(Selection selection);
086
087    void removeContext(Selection selection);
088
089    Operator getOperator();
090
091    /**
092     * Set the selection operator to use.
093     * @throws IllegalArgumentException if the operator cannot
094     * be used on the root selection member.
095     * @param operator Operator to apply on the selection.
096     */
097    void setOperator(Operator operator);
098
099    /**
100     * Defines which selection operators are allowed, relative to
101     * a root member.
102     */
103    public enum Operator {
104        /**
105         * Only the root member will be selected.
106         */
107        MEMBER,
108        /**
109         * All members of Level will be selected (LevelSelection only)
110         */
111        MEMBERS,
112        /**
113         * Only the children of the root member will be selected.
114         * This excludes the root member itself.
115         * <p>Implemented via the MDX .Children member property.
116         */
117        CHILDREN,
118        /**
119         * The root member will be selected along with all it's
120         * children.
121         */
122        INCLUDE_CHILDREN,
123        /**
124         * Will select the root member along with all it's siblings.
125         * <p>Implemented via the MDX .Siblings member property.
126         */
127        SIBLINGS,
128        /**
129         * Selects the set of the ascendants of a specified member,
130         * including the member itself.
131         * <p>Implemented via the MDX Ascendants() function.
132         */
133        ANCESTORS,
134        /**
135         * Selects the set of the descendants of a specified member,
136         * including the member itself.
137         * <p>Implemented via the MDX Descendants() function.
138         */
139        DESCENDANTS;
140    }
141}
142
143// End Selection.java