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    */
020    package org.olap4j.query;
021    
022    import org.olap4j.mdx.ParseTreeNode;
023    import org.olap4j.metadata.Dimension;
024    import org.olap4j.metadata.MetadataElement;
025    
026    import 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     */
047    public 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