Data Management

/**
 * Base interface for all datasets
 */
public interface Dataset {
    /**
     * Registers a change listener with the dataset
     * @param listener the listener to be registered
     */
    public void addChangeListener(DatasetChangeListener listener);
    
    /**
     * Deregisters a change listener from the dataset
     * @param listener the listener to be deregistered
     */
    public void removeChangeListener(DatasetChangeListener listener);
    
    /**
     * Returns the dataset group
     * @return the dataset group (possibly null)
     */
    public DatasetGroup getGroup();
    
    /**
     * Sets the dataset group
     * @param group the group
     */
    public void setGroup(DatasetGroup group);
}

/**
 * Base interface for datasets containing multiple data series
 */
public interface SeriesDataset extends Dataset {
    /**
     * Returns the number of series in the dataset
     * @return the series count
     */
    public int getSeriesCount();
    
    /**
     * Returns the key for a series
     * @param series the series index (zero-based)
     * @return the series key
     */
    public Comparable getSeriesKey(int series);
    
    /**
     * Returns the index of the series with the specified key
     * @param seriesKey the series key
     * @return the series index, or -1 if not found
     */
    public int indexOf(Comparable seriesKey);
}

/**
 * Interface for datasets containing category data (extends KeyedValues2D)
 */
public interface CategoryDataset extends KeyedValues2D, Dataset {
    // Inherited from KeyedValues2D:
    
    /**
     * Returns the number of rows (series) in the dataset
     * @return the row count
     */
    public int getRowCount();
    
    /**
     * Returns the number of columns (categories) in the dataset
     * @return the column count
     */
    public int getColumnCount();
    
    /**
     * Returns a value from the dataset
     * @param row the row index (zero-based)
     * @param column the column index (zero-based)
     * @return the value (possibly null)
     */
    public Number getValue(int row, int column);
    
    /**
     * Returns a value from the dataset using keys
     * @param rowKey the row key
     * @param columnKey the column key
     * @return the value (possibly null)
     */
    public Number getValue(Comparable rowKey, Comparable columnKey);
    
    /**
     * Returns the key for the specified row
     * @param row the row index (zero-based)
     * @return the row key
     */
    public Comparable getRowKey(int row);
    
    /**
     * Returns the key for the specified column
     * @param column the column index (zero-based)
     * @return the column key
     */
    public Comparable getColumnKey(int column);
    
    /**
     * Returns the row keys
     * @return a list of row keys
     */
    public List getRowKeys();
    
    /**
     * Returns the column keys
     * @return a list of column keys
     */
    public List getColumnKeys();
    
    /**
     * Returns the row index for a given key
     * @param key the row key
     * @return the row index, or -1 if not found
     */
    public int getRowIndex(Comparable key);
    
    /**
     * Returns the column index for a given key
     * @param key the column key
     * @return the column index, or -1 if not found
     */
    public int getColumnIndex(Comparable key);
}

/**
 * Default implementation of CategoryDataset
 */
public class DefaultCategoryDataset implements CategoryDataset {
    /**
     * Creates a new empty dataset
     */
    public DefaultCategoryDataset();
    
    /**
     * Adds a value to the dataset
     * @param value the value
     * @param rowKey the row key
     * @param columnKey the column key
     */
    public void addValue(Number value, Comparable rowKey, Comparable columnKey);
    
    /**
     * Adds a value to the dataset
     * @param value the value
     * @param rowKey the row key
     * @param columnKey the column key
     */
    public void addValue(double value, Comparable rowKey, Comparable columnKey);
    
    /**
     * Updates an existing value in the dataset
     * @param value the new value
     * @param rowKey the row key
     * @param columnKey the column key
     */
    public void setValue(Number value, Comparable rowKey, Comparable columnKey);
    
    /**
     * Removes a value from the dataset
     * @param rowKey the row key
     * @param columnKey the column key
     */
    public void removeValue(Comparable rowKey, Comparable columnKey);
    
    /**
     * Removes an entire row from the dataset
     * @param rowKey the row key
     */
    public void removeRow(Comparable rowKey);
    
    /**
     * Removes an entire column from the dataset
     * @param columnKey the column key
     */
    public void removeColumn(Comparable columnKey);
    
    /**
     * Clears all data from the dataset
     */
    public void clear();
}

/**
 * Category dataset with interval values (start and end values)
 */
public interface IntervalCategoryDataset extends CategoryDataset {
    /**
     * Returns the start value for an item
     * @param row the row index
     * @param column the column index
     * @return the start value
     */
    public Number getStartValue(int row, int column);
    
    /**
     * Returns the start value for an item using keys
     * @param rowKey the row key
     * @param columnKey the column key
     * @return the start value
     */
    public Number getStartValue(Comparable rowKey, Comparable columnKey);
    
    /**
     * Returns the end value for an item
     * @param row the row index
     * @param column the column index
     * @return the end value
     */
    public Number getEndValue(int row, int column);
    
    /**
     * Returns the end value for an item using keys
     * @param rowKey the row key
     * @param columnKey the column key
     * @return the end value
     */
    public Number getEndValue(Comparable rowKey, Comparable columnKey);
}

import org.jfree.data.category.DefaultCategoryDataset;

// Create and populate category dataset
DefaultCategoryDataset dataset = new DefaultCategoryDataset();

// Add data for quarterly sales
dataset.addValue(100.0, "Q1 2023", "Product A");
dataset.addValue(150.0, "Q1 2023", "Product B");
dataset.addValue(120.0, "Q1 2023", "Product C");

dataset.addValue(110.0, "Q2 2023", "Product A");
dataset.addValue(180.0, "Q2 2023", "Product B");
dataset.addValue(140.0, "Q2 2023", "Product C");

// Access data
Number value = dataset.getValue("Q1 2023", "Product A"); // 100.0
int rowCount = dataset.getRowCount(); // 2 quarters
int columnCount = dataset.getColumnCount(); // 3 products

// Remove specific data
dataset.removeValue("Q1 2023", "Product C");

// Clear all data
dataset.clear();

/**
 * Interface for XY coordinate datasets
 */
public interface XYDataset extends SeriesDataset {
    /**
     * Returns the order of the domain (X) values
     * @return the domain order
     */
    public DomainOrder getDomainOrder();
    
    /**
     * Returns the number of items in a series
     * @param series the series index (zero-based)
     * @return the item count
     */
    public int getItemCount(int series);
    
    /**
     * Returns the X value for a data item
     * @param series the series index (zero-based)
     * @param item the item index (zero-based)
     * @return the X value (possibly null)
     */
    public Number getX(int series, int item);
    
    /**
     * Returns the Y value for a data item
     * @param series the series index (zero-based)
     * @param item the item index (zero-based)
     * @return the Y value (possibly null)
     */
    public Number getY(int series, int item);
    
    /**
     * Returns the X value as a double primitive
     * @param series the series index (zero-based)
     * @param item the item index (zero-based)
     * @return the X value as double
     */
    public double getXValue(int series, int item);
    
    /**
     * Returns the Y value as a double primitive  
     * @param series the series index (zero-based)
     * @param item the item index (zero-based)
     * @return the Y value as double
     */
    public double getYValue(int series, int item);
}

/**
 * XY dataset with interval values
 */
public interface IntervalXYDataset extends XYDataset {
    /**
     * Returns the start X value for an item
     * @param series the series index
     * @param item the item index
     * @return the start X value
     */
    public Number getStartX(int series, int item);
    
    /**
     * Returns the end X value for an item
     * @param series the series index
     * @param item the item index
     * @return the end X value
     */
    public Number getEndX(int series, int item);
    
    /**
     * Returns the start Y value for an item
     * @param series the series index
     * @param item the item index
     * @return the start Y value
     */
    public Number getStartY(int series, int item);
    
    /**
     * Returns the end Y value for an item
     * @param series the series index
     * @param item the item index
     * @return the end Y value
     */
    public Number getEndY(int series, int item);
    
    // Primitive versions for performance
    public double getStartXValue(int series, int item);
    public double getEndXValue(int series, int item);
    public double getStartYValue(int series, int item);
    public double getEndYValue(int series, int item);
}

/**
 * XY dataset with Z (third dimension) values for bubble charts
 */
public interface XYZDataset extends XYDataset {
    /**
     * Returns the Z value for a data item
     * @param series the series index (zero-based)
     * @param item the item index (zero-based)
     * @return the Z value (possibly null)
     */
    public Number getZ(int series, int item);
    
    /**
     * Returns the Z value as a double primitive
     * @param series the series index (zero-based)
     * @param item the item index (zero-based)
     * @return the Z value as double
     */
    public double getZValue(int series, int item);
}

/**
 * Collection of XY series for creating multi-series XY datasets
 */
public class XYSeriesCollection implements XYDataset, IntervalXYDataset {
    /**
     * Creates a new empty collection
     */
    public XYSeriesCollection();
    
    /**
     * Adds a series to the collection
     * @param series the series
     */
    public void addSeries(XYSeries series);
    
    /**
     * Removes a series from the collection
     * @param series the series
     */
    public void removeSeries(XYSeries series);
    
    /**
     * Removes a series by index
     * @param series the series index
     */
    public void removeSeries(int series);
    
    /**
     * Removes all series from the collection
     */
    public void removeAllSeries();
    
    /**
     * Returns a series by index
     * @param series the series index
     * @return the series
     */
    public XYSeries getSeries(int series);
    
    /**
     * Returns a series by key
     * @param key the series key
     * @return the series, or null if not found
     */
    public XYSeries getSeries(Comparable key);
    
    /**
     * Returns the series index for a given key
     * @param key the series key
     * @return the series index, or -1 if not found
     */
    public int indexOf(Comparable key);
}

/**
 * Individual XY data series
 */
public class XYSeries implements Cloneable, Serializable {
    /**
     * Creates a new XY series
     * @param key the series key
     */
    public XYSeries(Comparable key);
    
    /**
     * Creates a new XY series with auto-sorting option
     * @param key the series key
     * @param autoSort flag to control automatic sorting by X value
     */
    public XYSeries(Comparable key, boolean autoSort);
    
    /**
     * Adds a data item to the series
     * @param x the X value
     * @param y the Y value
     */
    public void add(double x, double y);
    
    /**
     * Adds a data item to the series
     * @param x the X value
     * @param y the Y value
     */
    public void add(Number x, Number y);
    
    /**
     * Adds a data item with duplicate X value checking
     * @param x the X value
     * @param y the Y value
     * @param notify flag to control change notification
     */
    public void add(double x, double y, boolean notify);
    
    /**
     * Updates an existing data item or adds a new one
     * @param x the X value
     * @param y the Y value
     */
    public void addOrUpdate(double x, double y);
    
    /**
     * Updates an existing data item or adds a new one
     * @param x the X value
     * @param y the Y value
     */
    public void addOrUpdate(Number x, Number y);
    
    /**
     * Removes a data item
     * @param x the X value to remove
     */
    public void remove(Number x);
    
    /**
     * Removes a data item by index
     * @param index the item index
     */
    public void remove(int index);
    
    /**
     * Removes all data items
     */
    public void clear();
    
    /**
     * Returns a data item
     * @param index the item index
     * @return the data item
     */
    public XYDataItem getDataItem(int index);
    
    /**
     * Returns the number of data items
     * @return the item count
     */
    public int getItemCount();
    
    /**
     * Returns the X value for an item
     * @param index the item index
     * @return the X value
     */
    public Number getX(int index);
    
    /**
     * Returns the Y value for an item
     * @param index the item index
     * @return the Y value
     */
    public Number getY(int index);
    
    /**
     * Updates the Y value for an existing X value
     * @param x the X value
     * @param y the new Y value
     */
    public void updateByX(Number x, Number y);
    
    /**
     * Updates the Y value at a specific index
     * @param index the item index
     * @param y the new Y value
     */
    public void updateByIndex(int index, Number y);
    
    /**
     * Creates a copy of the series for a range of X values
     * @param start the start X value
     * @param end the end X value
     * @return a new series containing the data in the specified range
     */
    public XYSeries createCopy(int start, int end);
    
    /**
     * Converts the series data to arrays
     * @return an array containing [xArray, yArray]
     */
    public double[][] toArray();
}

import org.jfree.data.xy.*;

// Create XY series
XYSeries series1 = new XYSeries("Temperature");
series1.add(1.0, 20.5);
series1.add(2.0, 22.1);
series1.add(3.0, 19.8);
series1.add(4.0, 25.2);

XYSeries series2 = new XYSeries("Pressure");
series2.add(1.0, 1013.2);
series2.add(2.0, 1015.1);
series2.add(3.0, 1010.8);
series2.add(4.0, 1018.3);

// Create collection
XYSeriesCollection dataset = new XYSeriesCollection();
dataset.addSeries(series1);
dataset.addSeries(series2);

// Access data
double temp = dataset.getYValue(0, 1); // Temperature at point 1: 22.1
int seriesCount = dataset.getSeriesCount(); // 2
int itemCount = dataset.getItemCount(0); // 4 items in first series

// Update data
series1.addOrUpdate(5.0, 23.7); // Add new point or update existing
series1.updateByX(2.0, 21.5);   // Update Y value for X=2.0

/**
 * Time series data indexed by time periods
 */
public class TimeSeries implements Cloneable, Serializable {
    /**
     * Creates a new time series
     * @param name the series name
     */
    public TimeSeries(Comparable name);
    
    /**
     * Adds a data item to the series
     * @param period the time period
     * @param value the value
     */
    public void add(RegularTimePeriod period, Number value);
    
    /**
     * Adds a data item to the series
     * @param period the time period
     * @param value the value
     */
    public void add(RegularTimePeriod period, double value);
    
    /**
     * Adds a data item with notification control
     * @param period the time period
     * @param value the value
     * @param notify flag to control change notification
     */
    public void add(RegularTimePeriod period, Number value, boolean notify);
    
    /**
     * Updates an existing data item or adds a new one
     * @param period the time period
     * @param value the value
     */
    public void addOrUpdate(RegularTimePeriod period, Number value);
    
    /**
     * Updates an existing data item or adds a new one
     * @param period the time period
     * @param value the value
     */
    public void addOrUpdate(RegularTimePeriod period, double value);
    
    /**
     * Updates an existing data item by index
     * @param index the item index
     * @param value the new value
     */
    public void update(int index, Number value);
    
    /**
     * Updates an existing data item by time period
     * @param period the time period
     * @param value the new value
     */
    public void update(RegularTimePeriod period, Number value);
    
    /**
     * Removes a data item
     * @param period the time period to remove
     */
    public void delete(RegularTimePeriod period);
    
    /**
     * Removes a data item by index
     * @param index the item index
     */
    public void delete(int index);
    
    /**
     * Removes a range of data items
     * @param start the start index (inclusive)
     * @param end the end index (inclusive)
     */
    public void delete(int start, int end);
    
    /**
     * Removes all data items
     */
    public void clear();
    
    /**
     * Returns a data item
     * @param index the item index
     * @return the data item
     */
    public TimeSeriesDataItem getDataItem(int index);
    
    /**
     * Returns a data item by time period
     * @param period the time period
     * @return the data item, or null if not found
     */
    public TimeSeriesDataItem getDataItem(RegularTimePeriod period);
    
    /**
     * Returns the number of data items
     * @return the item count
     */
    public int getItemCount();
    
    /**
     * Returns the time period for an item
     * @param index the item index
     * @return the time period
     */
    public RegularTimePeriod getTimePeriod(int index);
    
    /**
     * Returns the value for an item
     * @param index the item index
     * @return the value
     */
    public Number getValue(int index);
    
    /**
     * Returns the value for a time period
     * @param period the time period
     * @return the value, or null if not found
     */
    public Number getValue(RegularTimePeriod period);
    
    /**
     * Creates a copy of the series for a time range
     * @param start the start period
     * @param end the end period
     * @return a new series containing data in the specified range
     */
    public TimeSeries createCopy(RegularTimePeriod start, RegularTimePeriod end);
    
    /**
     * Creates a copy of the series for an index range
     * @param start the start index
     * @param end the end index
     * @return a new series containing data in the specified range
     */
    public TimeSeries createCopy(int start, int end);
    
    /**
     * Removes aged items from the series
     * @param maxAge maximum age in milliseconds
     * @param notify flag to control change notification
     */
    public void removeAgedItems(long maxAge, boolean notify);
    
    /**
     * Gets the maximum number of items allowed in the series
     * @return the maximum item count
     */
    public int getMaximumItemCount();
    
    /**
     * Sets the maximum number of items allowed in the series
     * @param maximum the maximum item count
     */
    public void setMaximumItemCount(int maximum);
    
    /**
     * Gets the maximum age for items in the series
     * @return the maximum age in milliseconds
     */
    public long getMaximumItemAge();
    
    /**
     * Sets the maximum age for items in the series
     * @param periods the maximum age in time periods
     */
    public void setMaximumItemAge(long periods);
}

/**
 * Collection of time series for creating multi-series time-based datasets
 */
public class TimeSeriesCollection implements XYDataset, IntervalXYDataset {
    /**
     * Creates a new empty collection
     */
    public TimeSeriesCollection();
    
    /**
     * Creates a collection with a single time series
     * @param series the initial series
     */
    public TimeSeriesCollection(TimeSeries series);
    
    /**
     * Adds a time series to the collection
     * @param series the series
     */
    public void addSeries(TimeSeries series);
    
    /**
     * Removes a time series from the collection
     * @param series the series
     */
    public void removeSeries(TimeSeries series);
    
    /**
     * Removes a time series by index
     * @param index the series index
     */
    public void removeSeries(int index);
    
    /**
     * Removes all time series from the collection
     */
    public void removeAllSeries();
    
    /**
     * Returns a time series by index
     * @param series the series index
     * @return the time series
     */
    public TimeSeries getSeries(int series);
    
    /**
     * Returns a time series by key
     * @param key the series key
     * @return the time series, or null if not found
     */
    public TimeSeries getSeries(Comparable key);
    
    /**
     * Returns the series index for a given key
     * @param key the series key
     * @return the series index, or -1 if not found
     */
    public int indexOf(Comparable key);
}

import org.jfree.data.time.*;

// Create time series
TimeSeries stockPrice = new TimeSeries("AAPL");
stockPrice.add(new Day(1, 1, 2023), 150.0);
stockPrice.add(new Day(2, 1, 2023), 152.5);
stockPrice.add(new Day(3, 1, 2023), 148.2);

// Configure automatic aging
stockPrice.setMaximumItemCount(100);    // Keep last 100 items
stockPrice.setMaximumItemAge(365);      // Keep items up to 365 days old

// Update values
stockPrice.addOrUpdate(new Day(3, 1, 2023), 149.8); // Update existing
stockPrice.addOrUpdate(new Day(4, 1, 2023), 151.3); // Add new

// Create collection
TimeSeriesCollection dataset = new TimeSeriesCollection();
dataset.addSeries(stockPrice);

// Access data
Number value = stockPrice.getValue(new Day(2, 1, 2023)); // 152.5
int itemCount = stockPrice.getItemCount(); // 4 items

// Create subset
TimeSeries lastWeek = stockPrice.createCopy(
    new Day(28, 12, 2022), new Day(4, 1, 2023));

/**
 * Dataset for pie charts (extends KeyedValues)
 */
public interface PieDataset<K> extends KeyedValues<K>, Dataset {
    // Inherited from KeyedValues<K>:
    
    /**
     * Returns the number of items in the dataset
     * @return the item count
     */
    public int getItemCount();
    
    /**
     * Returns a value by key
     * @param key the key
     * @return the value (possibly null)
     */
    public Number getValue(K key);
    
    /**
     * Returns a value by index
     * @param item the item index (zero-based)
     * @return the value (possibly null)
     */
    public Number getValue(int item);
    
    /**
     * Returns a key by index
     * @param item the item index (zero-based)
     * @return the key
     */
    public K getKey(int item);
    
    /**
     * Returns all keys
     * @return a list of keys
     */
    public List<K> getKeys();
    
    /**
     * Returns the index for a given key
     * @param key the key
     * @return the index, or -1 if not found
     */
    public int getIndex(K key);
}

/**
 * Default implementation of PieDataset
 */
public class DefaultPieDataset<K> implements PieDataset<K> {
    /**
     * Creates a new empty pie dataset
     */
    public DefaultPieDataset();
    
    /**
     * Sets a value in the dataset
     * @param key the key
     * @param value the value
     */
    public void setValue(K key, Number value);
    
    /**
     * Sets a value in the dataset
     * @param key the key
     * @param value the value
     */
    public void setValue(K key, double value);
    
    /**
     * Removes a value from the dataset
     * @param key the key
     */
    public void remove(K key);
    
    /**
     * Removes all values from the dataset
     */
    public void clear();
    
    /**
     * Sorts the dataset by keys
     * @param order the sort order (ASCENDING or DESCENDING)
     */
    public void sortByKeys(SortOrder order);
    
    /**
     * Sorts the dataset by values
     * @param order the sort order (ASCENDING or DESCENDING)
     */
    public void sortByValues(SortOrder order);
}

import org.jfree.data.general.DefaultPieDataset;

// Create pie dataset
DefaultPieDataset<String> dataset = new DefaultPieDataset<>();
dataset.setValue("Chrome", 65.2);
dataset.setValue("Firefox", 18.7);
dataset.setValue("Safari", 9.6);
dataset.setValue("Edge", 4.8);
dataset.setValue("Other", 1.7);

// Access data
Number chromeShare = dataset.getValue("Chrome"); // 65.2
int categories = dataset.getItemCount(); // 5
String topBrowser = dataset.getKey(0); // First key

// Sort by values (descending)
dataset.sortByValues(SortOrder.DESCENDING);

// Remove small categories
dataset.remove("Other");

// Clear all data
dataset.clear();

// Financial data for candlestick and high-low charts
public interface OHLCDataset extends XYDataset {
    public Number getHigh(int series, int item);
    public double getHighValue(int series, int item);
    public Number getLow(int series, int item);
    public double getLowValue(int series, int item);
    public Number getOpen(int series, int item);
    public double getOpenValue(int series, int item);
    public Number getClose(int series, int item);
    public double getCloseValue(int series, int item);
    public Number getVolume(int series, int item);
    public double getVolumeValue(int series, int item);
}

// Statistical data for box and whisker plots  
public interface BoxAndWhiskerCategoryDataset extends CategoryDataset {
    public Number getMean(int row, int column);
    public Number getMean(Comparable rowKey, Comparable columnKey);
    public Number getMedian(int row, int column);
    public Number getMedian(Comparable rowKey, Comparable columnKey);
    public Number getQ1(int row, int column);
    public Number getQ1(Comparable rowKey, Comparable columnKey);
    public Number getQ3(int row, int column);
    public Number getQ3(Comparable rowKey, Comparable columnKey);
    public Number getMinRegularValue(int row, int column);
    public Number getMinRegularValue(Comparable rowKey, Comparable columnKey);
    public Number getMaxRegularValue(int row, int column);
    public Number getMaxRegularValue(Comparable rowKey, Comparable columnKey);
    public List getOutliers(int row, int column);
    public List getOutliers(Comparable rowKey, Comparable columnKey);
}

// 3D datasets for bubble charts
public class DefaultXYZDataset implements XYZDataset {
    public DefaultXYZDataset();
    public void addSeries(Comparable seriesKey, double[][] data);
    public void removeSeries(Comparable seriesKey);
    public void removeAllSeries();
}

// Gantt chart datasets
public interface GanttCategoryDataset extends IntervalCategoryDataset {
    public Number getPercentComplete(int row, int column);
    public Number getPercentComplete(Comparable rowKey, Comparable columnKey);
    public int getSubIntervalCount(int row, int column);
    public int getSubIntervalCount(Comparable rowKey, Comparable columnKey);
    public Number getStartValue(int row, int column, int subinterval);
    public Number getEndValue(int row, int column, int subinterval);
    public Number getPercentComplete(int row, int column, int subinterval);
}