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