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