001    /*
002    // $Id: Cube.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    import java.util.*;
015    
016    /**
017     * Central metadata object for representation of multidimensional data.
018     *
019     * <p>A Cube belongs to a {@link Schema}, and is described by a list of
020     * {@link Dimension}s and a list of {@link Measure}s. It may also have one or
021     * more {@link NamedSet}s.
022     *
023     * @see org.olap4j.metadata.Cube#getMeasures()
024     *
025     * @author jhyde
026     * @version $Id: Cube.java 229 2009-05-08 19:11:29Z jhyde $
027     * @since Aug 22, 2006
028     */
029    public interface Cube extends MetadataElement {
030        /**
031         * Returns the {@link Schema} this Cube belongs to.
032         *
033         * @return Schema this Cube belongs to
034         */
035        Schema getSchema();
036    
037        /**
038         * Returns a list of {@link Dimension} objects in this Cube.
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#getDimensions(String,String,String,String)
044         *
045         * @return list of Dimensions
046         */
047        NamedList<Dimension> getDimensions();
048    
049        /**
050         * Returns a list of {@link Hierarchy} objects in this Cube.
051         *
052         * <p>The caller should assume that the list is immutable;
053         * if the caller modifies the list, behavior is undefined.</p>
054         *
055         * @see org.olap4j.OlapDatabaseMetaData#getHierarchies(String, String, String, String, String)
056         *
057         * @return list of Dimensions
058         */
059        NamedList<Hierarchy> getHierarchies();
060    
061        /**
062         * Returns a list of {@link Measure} objects in this Cube.
063         *
064         * <p>The list includes both stored and calculated members, and (unlike
065         * the {@link org.olap4j.OlapDatabaseMetaData#getMeasures} method or the
066         * MDSCHEMA_MEASURES XMLA request) is sorted by ordinal.
067         *
068         * @see org.olap4j.OlapDatabaseMetaData#getMeasures(String,String,String,String,String)
069         *
070         * @return list of Measures
071         */
072        List<Measure> getMeasures();
073    
074        /**
075         * Returns a list of {@link NamedSet} objects in this Cube.
076         *
077         * <p>The caller should assume that the list is immutable;
078         * if the caller modifies the list, behavior is undefined.</p>
079         *
080         * @see org.olap4j.OlapDatabaseMetaData#getSets(String,String,String,String)
081         *
082         * @return list of NamedSets
083         */
084        NamedList<NamedSet> getSets();
085    
086        /**
087         * Returns a collection of {@link java.util.Locale} objects for which this
088         * <code>Cube</code> has been localized.
089         *
090         * <p>Consider the following use case. Suppose one cube is available in
091         * English and French, and in French and Spanish, and both are shown in same
092         * portal. Clients typically say that seeing reports in a mixture of
093         * languages is confusing; the portal would figure out the best common
094         * language, in this case French. This method allows the client to choose
095         * the most appropriate locale.</p>
096         *
097         * <p>The list is advisory: a client is free to choose another locale,
098         * in which case, the server will probably revert to the base locale for
099         * locale-specific behavior such as captions and formatting.</p>
100         *
101         * @see Schema#getSupportedLocales
102         *
103         * @return List of locales for which this <code>Cube</code> has been
104         * localized
105         */
106        Collection<Locale> getSupportedLocales();
107    
108        /**
109         * Finds a member in the current Cube based upon its fully-qualified name.
110         * Returns the member, or null if there is no member with this name.
111         *
112         * <p>The fully-qualified name starts with the name of the dimension,
113         * followed by the name of a root member, and continues with the name of
114         * each successive member on the path from the root member. If a member's
115         * name is unique within its level, preceding member name can be omitted.
116         *
117         * <p>For example,
118         * <code>lookupMember("Product", "Food")</code>
119         * and
120         * <code>lookupMember("Product", "All Products", "Food")</code>
121         * are both valid ways to locate the "Food" member of the "Product"
122         * dimension.
123         *
124         * @param nameParts Components of the fully-qualified member name
125         *
126         * @return member with the given name, or null if not found
127         *
128         * @throws OlapException if error occurs
129         */
130        Member lookupMember(String... nameParts) throws OlapException;
131    
132        /**
133         * Finds a collection of members in the current Cube related to a given
134         * member.
135         *
136         * <p>The method first looks up a member with the given fully-qualified
137         * name as for {@link #lookupMember(String[])}, then applies the set of
138         * tree-operations to find related members.
139         *
140         * <p>The returned collection is sorted by level number then by member
141         * ordinal. If no member is found with the given name, the collection is
142         * empty.
143         *
144         * <p>For example,
145         *
146         * <blockquote><pre>
147         * <code>lookupMembers(
148         *     EnumSet.of(TreeOp.ANCESTORS, TreeOp.CHILDREN),
149         *     "Time", "1997", "Q2")</code>
150         * </pre></blockquote>
151         *
152         * returns
153         *
154         * <blockquote><pre><code>
155         * [Time].[1997]
156         * [Time].[1997].[Q2].[4]
157         * [Time].[1997].[Q2].[5]
158         * [Time].[1997].[Q2].[6]
159         * </code></pre></blockquote>
160         *
161         * <p>The fully-qualified name starts with the name of the dimension,
162         * followed by the name of a root member, and continues with the name of
163         * each successive member on the path from the root member. If a member's
164         * name is unique within its level, preceding member name can be omitted.
165         *
166         * <p>For example,
167         * <code>lookupMember("Product", "Food")</code>
168         * and
169         * <code>lookupMember("Product", "All Products", "Food")</code>
170         * are both valid ways to locate the "Food" member of the "Product"
171         * dimension.
172         *
173         * @param nameParts Components of the fully-qualified member name
174         *
175         * @param treeOps Collection of tree operations to travel relative to
176         * given member in order to create list of members
177         *
178         * @return collection of members related to the given member, or empty
179         * set if the member is not found
180         *
181         * @throws OlapException if error occurs
182         */
183        List<Member> lookupMembers(
184            Set<Member.TreeOp> treeOps,
185            String... nameParts) throws OlapException;
186    }
187    
188    // End Cube.java