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*/
020package org.olap4j.metadata;
021
022import org.olap4j.OlapException;
023import org.olap4j.mdx.IdentifierSegment;
024
025import 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 */
040public 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