001/* ===========================================================
002 * Orson Charts : a 3D chart library for the Java(tm) platform
003 * ===========================================================
004 * 
005 * (C)opyright 2013-2022, by David Gilbert.  All rights reserved.
006 * 
007 * https://github.com/jfree/orson-charts
008 * 
009 * This program is free software: you can redistribute it and/or modify
010 * it under the terms of the GNU General Public License as published by
011 * the Free Software Foundation, either version 3 of the License, or
012 * (at your option) any later version.
013 *
014 * This program is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
017 * GNU General Public License for more details.
018 *
019 * You should have received a copy of the GNU General Public License
020 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
021 * 
022 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
023 * Other names may be trademarks of their respective owners.]
024 * 
025 * If you do not wish to be bound by the terms of the GPL, an alternative
026 * commercial license can be purchased.  For details, please see visit the
027 * Orson Charts home page:
028 * 
029 * http://www.object-refinery.com/orsoncharts/index.html
030 * 
031 */
032
033package org.jfree.chart3d.data;
034
035import java.util.List;
036
037/**
038 * A three dimensional cube of data values where each value is uniquely 
039 * identified by three keys (the {@code seriesKey}, {@code rowKey} 
040 * and {@code columnKey}).
041 * 
042 * @param <S> The series key type.
043 * @param <R> The row key type.
044 * @param <C> The column key type.
045 * @param <T> The value type.
046 */
047public interface KeyedValues3D<S extends Comparable<S>, 
048        R extends Comparable<R>, C extends Comparable<C>, T> 
049        extends Values3D<T> {
050
051    /**
052     * Returns a list of the series keys for the dataset.  Modifying this
053     * list will have no impact on the underlying dataset.
054     * 
055     * @return A list of the series keys (possibly empty, but never 
056     *     {@code null}). 
057     */
058    List<S> getSeriesKeys();
059
060    /**
061     * Returns a list of the row keys for the dataset.  Modifying this
062     * list will have no impact on the underlying dataset.
063     * 
064     * @return A list of the row keys (possibly empty, but never 
065     *     {@code null}). 
066     */
067    List<R> getRowKeys();
068    
069    /**
070     * Returns a list of the column keys for the dataset.  Modifying this
071     * list will have no impact on the underlying dataset.
072     * 
073     * @return A list of the column keys (possibly empty, but never 
074     *     {@code null}). 
075     */
076    List<C> getColumnKeys();
077    
078    /**
079     * Returns the series key with the specified index.
080     * 
081     * @param seriesIndex  the series index.
082     * 
083     * @return The key. 
084     */
085    S getSeriesKey(int seriesIndex);
086
087    /**
088     * Returns the row key with the specified index.
089     * 
090     * @param rowIndex  the row index.
091     * 
092     * @return The key. 
093     */    
094    R getRowKey(int rowIndex);
095
096    /**
097     * Returns the column key with the specified index.
098     * 
099     * @param columnIndex  the column index.
100     * 
101     * @return The key. 
102     */    
103    C getColumnKey(int columnIndex);
104
105    /**
106     * Returns the index of the specified series key, or {@code -1} if
107     * there is no matching key.
108     * 
109     * @param serieskey  the series key ({@code null} not permitted).
110     * 
111     * @return The key index, or {@code -1}. 
112     */
113    int getSeriesIndex(S serieskey);
114
115    /**
116     * Returns the index of the specified row key, or {@code -1} if there
117     * is no matching key.
118     * 
119     * @param rowkey  the row key ({@code null} not permitted).
120     * 
121     * @return The row index or {@code -1}. 
122     */
123    int getRowIndex(R rowkey);
124
125    /**
126     * Returns the index of the specified column key, or {@code -1} if 
127     * there is no matching key.
128     * 
129     * @param columnkey  the column key ({@code null} not permitted).
130     * 
131     * @return The column index or {@code -1}. 
132     */
133    int getColumnIndex(C columnkey);
134
135    /**
136     * Returns the value for a given series, row and column.
137     * 
138     * @param seriesKey the series key ({@code null} not permitted).
139     * @param rowKey  the row key ({@code null} not permitted).
140     * @param columnKey  the column key ({@code null} not permitted).
141     * 
142     * @return The value (possibly {@code null}).
143     */
144    T getValue(S seriesKey, R rowKey, C columnKey);
145    
146}