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 two dimensional grid of data values where each value is uniquely 
039 * identified by two keys (the {@code rowKey} and the 
040 * {@code columnKey}).  Any instance of {@code Comparable} can be 
041 * used as a key ({@code String} objects are instances of 
042 * {@code Comparable}, making them convenient key objects).
043 * 
044 * @param <R>  The row key type.
045 * @param <C>  The column key type.
046 * @param <T>  The value type.
047 */
048public interface KeyedValues2D<R extends Comparable<R>, 
049        C extends Comparable<C>, T> extends Values2D<T> {
050
051    /**
052     * Returns the row key with the specified index.
053     * 
054     * @param rowIndex  the row index.
055     * 
056     * @return The key. 
057     */
058    R getRowKey(int rowIndex);
059
060    /**
061     * Returns the column key with the specified index.
062     * 
063     * @param columnIndex  the index.
064     * 
065     * @return The key. 
066     */
067    C getColumnKey(int columnIndex);
068
069    /**
070     * Returns the index of the specified key, or {@code -1} if there
071     * is no such key.
072     * 
073     * @param rowKey  the row key ({@code null} not permitted).
074     * 
075     * @return The index, or {@code -1}. 
076     */
077    int getRowIndex(R rowKey);
078
079    /**
080     * Returns the index of the specified key, or {@code -1} if there
081     * is no such key.
082     * 
083     * @param columnKey  the column key ({@code null} not permitted).
084     * 
085     * @return The index, or {@code -1}. 
086     */
087    int getColumnIndex(C columnKey);
088  
089    /**
090     * Returns a list of the row keys (the order is significant, since data 
091     * values can be accessed by index as well as by key).
092     * <br><br>
093     * NOTE: this method must be implemented so that modifications to the
094     * returned list do not impact the underlying data structure.
095     * 
096     * @return A list of row keys.
097     */
098    List<R> getRowKeys();
099
100    /**
101     * Returns a list of the column keys (the order is significant, since data 
102     * values can be accessed by index as well as by key).
103     * <br><br>
104     * NOTE: this method must be implemented so that modifications to the
105     * returned list do not impact the underlying data structure.
106     * 
107     * @return A list of column keys.
108     */
109    List<C> getColumnKeys();
110
111    /**
112     * Returns the value (possibly {@code null}) associated with the 
113     * specified keys.  If either or both of the keys is not defined in this
114     * data structure, a runtime exception will be thrown.
115     * 
116     * @param rowKey  the row key ({@code null} not permitted).
117     * @param columnKey  the column key ({@code null} not permitted).
118     * 
119     * @return The value (possibly {@code null}). 
120     */
121    T getValue(R rowKey, C columnKey);
122
123}