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