001/*
002// $Id: Axis.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;
021
022import java.util.Locale;
023
024/**
025 * Enumeration of axis types.
026 *
027 * <p>The most commonly used values are
028 * <code>COLUMNS</code> (the first axis of a 2-dimensional query),
029 * <code>ROWS</code> (the second axis of a 2-dimensional query) and
030 * <code>FILTER</code> (also known as the slicer axis, denoted by a
031 * <code>WHERE</code> clause in an MDX statement).
032 *
033 * @author jhyde
034 * @version $Id: Axis.java 482 2012-01-05 23:27:27Z jhyde $
035 * @since Oct 23, 2006
036 */
037public interface Axis {
038
039    /**
040     * Abbreviation for {@link org.olap4j.Axis.Standard#FILTER}.
041     */
042    Standard FILTER = Standard.FILTER;
043
044    /**
045     * Abbreviation for {@link org.olap4j.Axis.Standard#COLUMNS}.
046     */
047    Standard COLUMNS = Standard.COLUMNS;
048
049    /**
050     * Abbreviation for {@link org.olap4j.Axis.Standard#ROWS}.
051     */
052    Standard ROWS = Standard.ROWS;
053
054    /**
055     * Abbreviation for {@link org.olap4j.Axis.Standard#PAGES}.
056     */
057    Standard PAGES = Standard.PAGES;
058
059    /**
060     * Abbreviation for {@link org.olap4j.Axis.Standard#CHAPTERS}.
061     */
062    Standard SECTIONS = Standard.SECTIONS;
063
064    /**
065     * Abbreviation for {@link org.olap4j.Axis.Standard#FILTER}.
066     */
067    Standard CHAPTERS = Standard.CHAPTERS;
068
069    /**
070     * Returns the name of this axis, e.g. "COLUMNS", "FILTER", "AXIS(17)".
071     *
072     * @return Name of the axis
073     */
074    String name();
075
076    /**
077     * Returns whether this is the filter (slicer) axis.
078     *
079     * @return whether this is the filter axis
080     */
081    boolean isFilter();
082
083
084    /**
085     * Returns the ordinal which is to be used for retrieving this axis from
086     * the {@link org.olap4j.CellSet#getAxes()}, or retrieving its
087     * coordinate from {@link Cell#getCoordinateList()}.
088     *
089     * <p>For example:
090     * <ul>
091     * <li>-1 {@link org.olap4j.Axis.Standard#FILTER FILTER}</li>
092     * <li>0 {@link org.olap4j.Axis.Standard#COLUMNS COLUMNS}</li>
093     * <li>1 {@link org.olap4j.Axis.Standard#ROWS ROWS}</li>
094     * <li>2 {@link org.olap4j.Axis.Standard#PAGES PAGES}</li>
095     * <li>3 {@link org.olap4j.Axis.Standard#CHAPTERS CHAPTERS}</li>
096     * <li>4 {@link org.olap4j.Axis.Standard#SECTIONS SECTIONS}</li>
097     * <li>5 {@link org.olap4j.Axis.Standard#SECTIONS SECTIONS}</li>
098     * <li>6 AXES(6)</li>
099     * <li>123 AXES(123)</li>
100     * </ul>
101     *
102     * @return ordinal of this axis
103     */
104    int axisOrdinal();
105
106    /**
107     * Returns localized name for this Axis.
108     *
109     * <p>Examples: "FILTER", "ROWS", "COLUMNS", "AXIS(10)".
110     *
111     * @param locale Locale for which to give the name
112     * @return localized name for this Axis
113     */
114    String getCaption(Locale locale);
115
116    /**
117     * Enumeration of standard, named axes descriptors.
118     */
119    public enum Standard implements Axis {
120        /**
121         * Filter axis, also known as the slicer axis, and represented by the
122         * WHERE clause of an MDX query.
123         */
124        FILTER,
125
126        /** COLUMNS axis, also known as X axis and AXIS(0). */
127        COLUMNS,
128
129        /** ROWS axis, also known as Y axis and AXIS(1). */
130        ROWS,
131
132        /** PAGES axis, also known as AXIS(2). */
133        PAGES,
134
135        /** CHAPTERS axis, also known as AXIS(3). */
136        CHAPTERS,
137
138        /** SECTIONS axis, also known as AXIS(4). */
139        SECTIONS;
140
141        public int axisOrdinal() {
142            return ordinal() - 1;
143        }
144
145        public boolean isFilter() {
146            return this == FILTER;
147        }
148
149        public String getCaption(Locale locale) {
150            // TODO: localize
151            return name();
152        }
153    }
154
155    /**
156     * Container class for various Axis factory methods.
157     */
158    class Factory {
159        private static final Standard[] STANDARD_VALUES = Standard.values();
160
161        /**
162         * Returns the axis with a given ordinal.
163         *
164         * <p>For example, {@code forOrdinal(0)} returns the COLUMNS axis;
165         * {@code forOrdinal(-1)} returns the SLICER axis;
166         * {@code forOrdinal(100)} returns AXIS(100).
167         *
168         * @param ordinal Axis ordinal
169         * @return Axis whose ordinal is as given
170         */
171        public static Axis forOrdinal(final int ordinal) {
172            if (ordinal < -1) {
173                throw new IllegalArgumentException(
174                    "Axis ordinal must be -1 or higher");
175            }
176            if (ordinal + 1 < STANDARD_VALUES.length) {
177                return STANDARD_VALUES[ordinal + 1];
178            }
179            return new Axis() {
180                public String toString() {
181                    return name();
182                }
183
184                public String name() {
185                    return "AXIS(" + ordinal + ")";
186                }
187
188                public boolean isFilter() {
189                    return false;
190                }
191
192                public int axisOrdinal() {
193                    return ordinal;
194                }
195
196                public String getCaption(Locale locale) {
197                    // TODO: localize
198                    return name();
199                }
200            };
201        }
202    }
203}
204
205// End Axis.java