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*/
020package org.olap4j.metadata;
021
022import 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 */
038public 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