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 * 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 * 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