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