001/*
002// Licensed to Julian Hyde under one or more contributor license
003// agreements. See the NOTICE file distributed with this work for
004// additional information regarding copyright ownership.
005//
006// Julian Hyde licenses this file to you under the Apache License,
007// Version 2.0 (the "License"); you may not use this file except in
008// compliance with the License. You may obtain a copy of the License at:
009//
010// http://www.apache.org/licenses/LICENSE-2.0
011//
012// Unless required by applicable law or agreed to in writing, software
013// distributed under the License is distributed on an "AS IS" BASIS,
014// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015// See the License for the specific language governing permissions and
016// limitations under the License.
017*/
018package org.olap4j.metadata;
019
020import org.olap4j.OlapException;
021
022/**
023 * An organization of the set of {@link Member}s in a {@link Dimension} and
024 * their positions relative to one another.
025 *
026 * <p>A Hierarchy is a collection of {@link Level}s, each of which is a
027 * category of similar {@link Member}s.</p>
028 *
029 * <p>A Dimension must have at least one Hierarchy, and may have more than one,
030 * but most have exactly one Hierarchy.</p>
031 *
032 * @author jhyde
033 * @since Aug 23, 2006
034 */
035public interface Hierarchy extends MetadataElement {
036    /**
037     * Returns the {@link Dimension} this <code>Hierarchy</code> belongs to.
038     *
039     * @return dimension this hierarchy belongs to
040     */
041    Dimension getDimension();
042
043    /**
044     * Returns a list of the {@link Level} objects in this
045     * <code>Hierarchy</code>.
046     *
047     * <p>The caller should assume that the list is immutable;
048     * if the caller modifies the list, behavior is undefined.</p>
049     *
050     * @see org.olap4j.OlapDatabaseMetaData#getLevels
051     *
052     * @return list of levels
053     */
054    NamedList<Level> getLevels();
055
056    /**
057     * Returns whether this <code>Hierarchy</code> has an 'all' member.
058     *
059     * @return whether this hierarchy has an 'all' member
060     */
061    boolean hasAll();
062
063    /**
064     * Returns the default {@link Member} of this <code>Hierarchy</code>.
065     *
066     * <p>If the hierarchy has an 'all' member, this member is often the
067     * default.
068     *
069     * @return the default member of this hierarchy
070     */
071    Member getDefaultMember() throws OlapException;
072
073    /**
074     * Returns the root member or members of this Dimension.
075     *
076     * <p>If the dimension has an 'all' member, then this will be the sole
077     * root member.
078     *
079     * <p>The caller should assume that the list is immutable;
080     * if the caller modifies the list, behavior is undefined.</p>
081     *
082     * <p>The result is similar to that returned by
083     * <code>getLevels().get(0).getMembers()</code>; the contents will be the
084     * same, but this method returns a {@link NamedList} rather than a
085     * mere {@link java.util.List} because the members of the root level are
086     * known to have unique names.
087     *
088     * @return root members of this hierarchy
089     *
090     * @throws OlapException on database error
091     */
092    NamedList<Member> getRootMembers() throws OlapException;
093}
094
095// End Hierarchy.java