001    /*
002    // $Id: Hierarchy.java 229 2009-05-08 19:11:29Z jhyde $
003    // This software is subject to the terms of the Eclipse Public License v1.0
004    // Agreement, available at the following URL:
005    // http://www.eclipse.org/legal/epl-v10.html.
006    // Copyright (C) 2006-2008 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package org.olap4j.metadata;
011    
012    import org.olap4j.OlapException;
013    
014    /**
015     * An organization of the set of {@link Member}s in a {@link Dimension} and
016     * their positions relative to one another.
017     *
018     * <p>A Hierarchy is a collection of {@link Level}s, each of which is a
019     * category of similar {@link Member}s.</p>
020     *
021     * <p>A Dimension must have at least one Hierarchy, and may have more than one,
022     * but most have exactly one Hierarchy.</p>
023     *
024     * @author jhyde
025     * @version $Id: Hierarchy.java 229 2009-05-08 19:11:29Z jhyde $
026     * @since Aug 23, 2006
027     */
028    public interface Hierarchy extends MetadataElement {
029        /**
030         * Returns the {@link Dimension} this <code>Hierarchy</code> belongs to.
031         *
032         * @return dimension this hierarchy belongs to
033         */
034        Dimension getDimension();
035    
036        /**
037         * Returns a list of the {@link Level} objects in this
038         * <code>Hierarchy</code>.
039         *
040         * <p>The caller should assume that the list is immutable;
041         * if the caller modifies the list, behavior is undefined.</p>
042         *
043         * @see org.olap4j.OlapDatabaseMetaData#getLevels
044         *
045         * @return list of levels
046         */
047        NamedList<Level> getLevels();
048    
049        /**
050         * Returns whether this <code>Hierarchy</code> has an 'all' member.
051         *
052         * @return whether this hierarchy has an 'all' member
053         */
054        boolean hasAll();
055    
056        /**
057         * Returns the default {@link Member} of this <code>Hierarchy</code>.
058         *
059         * <p>If the hierarchy has an 'all' member, this member is often the
060         * default.
061         *
062         * @return the default member of this hierarchy
063         */
064        Member getDefaultMember() throws OlapException;
065    
066        /**
067         * Returns the root member or members of this Dimension.
068         *
069         * <p>If the dimension has an 'all' member, then this will be the sole
070         * root member.
071         *
072         * <p>The caller should assume that the list is immutable;
073         * if the caller modifies the list, behavior is undefined.</p>
074         *
075         * <p>The result is similar to that returned by
076         * <code>getLevels().get(0).getMembers()</code>; the contents will be the
077         * same, but this method returns a {@link NamedList} rather than a
078         * mere {@link java.util.List} because the members of the root level are
079         * known to have unique names.
080         *
081         * @return root members of this hierarchy
082         *
083         * @throws OlapException on database error
084         */
085        NamedList<Member> getRootMembers() throws OlapException;
086    }
087    
088    // End Hierarchy.java