001    /*
002    // $Id: Hierarchy.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.metadata;
021    
022    import org.olap4j.OlapException;
023    
024    /**
025     * An organization of the set of {@link Member}s in a {@link Dimension} and
026     * their positions relative to one another.
027     *
028     * <p>A Hierarchy is a collection of {@link Level}s, each of which is a
029     * category of similar {@link Member}s.</p>
030     *
031     * <p>A Dimension must have at least one Hierarchy, and may have more than one,
032     * but most have exactly one Hierarchy.</p>
033     *
034     * @author jhyde
035     * @version $Id: Hierarchy.java 482 2012-01-05 23:27:27Z jhyde $
036     * @since Aug 23, 2006
037     */
038    public interface Hierarchy extends MetadataElement {
039        /**
040         * Returns the {@link Dimension} this <code>Hierarchy</code> belongs to.
041         *
042         * @return dimension this hierarchy belongs to
043         */
044        Dimension getDimension();
045    
046        /**
047         * Returns a list of the {@link Level} objects in this
048         * <code>Hierarchy</code>.
049         *
050         * <p>The caller should assume that the list is immutable;
051         * if the caller modifies the list, behavior is undefined.</p>
052         *
053         * @see org.olap4j.OlapDatabaseMetaData#getLevels
054         *
055         * @return list of levels
056         */
057        NamedList<Level> getLevels();
058    
059        /**
060         * Returns whether this <code>Hierarchy</code> has an 'all' member.
061         *
062         * @return whether this hierarchy has an 'all' member
063         */
064        boolean hasAll();
065    
066        /**
067         * Returns the default {@link Member} of this <code>Hierarchy</code>.
068         *
069         * <p>If the hierarchy has an 'all' member, this member is often the
070         * default.
071         *
072         * @return the default member of this hierarchy
073         */
074        Member getDefaultMember() throws OlapException;
075    
076        /**
077         * Returns the root member or members of this Dimension.
078         *
079         * <p>If the dimension has an 'all' member, then this will be the sole
080         * root member.
081         *
082         * <p>The caller should assume that the list is immutable;
083         * if the caller modifies the list, behavior is undefined.</p>
084         *
085         * <p>The result is similar to that returned by
086         * <code>getLevels().get(0).getMembers()</code>; the contents will be the
087         * same, but this method returns a {@link NamedList} rather than a
088         * mere {@link java.util.List} because the members of the root level are
089         * known to have unique names.
090         *
091         * @return root members of this hierarchy
092         *
093         * @throws OlapException on database error
094         */
095        NamedList<Member> getRootMembers() throws OlapException;
096    }
097    
098    // End Hierarchy.java