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