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