0
# JFreeChart
1

2
JFreeChart is a comprehensive free chart library for the Java platform that enables developers to create professional-quality charts for both client-side (JavaFX and Swing) and server-side applications with export capabilities to multiple formats including PNG and JPEG. Built on the Java2D API, it supports a wide range of chart types including bar charts, pie charts, line charts, XY-plots, time series plots, histograms, box plots, financial charts, and specialized charts for scientific and engineering applications.
3

4
## Package Information
5

6
- **Package Name**: org.jfree:jfreechart
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to `pom.xml`:
10
  ```xml
11
  <dependency>
12
      <groupId>org.jfree</groupId>
13
      <artifactId>jfreechart</artifactId>
14
      <version>1.5.5</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.jfree.chart.ChartFactory;
22
import org.jfree.chart.JFreeChart;
23
import org.jfree.chart.ChartPanel;
24
import org.jfree.chart.ChartUtils;
25
import org.jfree.data.category.DefaultCategoryDataset;
26
import org.jfree.data.xy.XYSeriesCollection;
27
```
28

29
## Basic Usage
30

31
```java
32
import org.jfree.chart.*;
33
import org.jfree.data.category.DefaultCategoryDataset;
34
import javax.swing.JFrame;
35

36
// Create a simple bar chart
37
DefaultCategoryDataset dataset = new DefaultCategoryDataset();
38
dataset.addValue(100, "Series1", "Category1");
39
dataset.addValue(200, "Series1", "Category2");
40
dataset.addValue(150, "Series1", "Category3");
41

42
JFreeChart chart = ChartFactory.createBarChart(
43
    "Sales Report",     // chart title
44
    "Category",         // domain axis label
45
    "Value",           // range axis label
46
    dataset            // data
47
);
48

49
// Display in Swing application
50
ChartPanel chartPanel = new ChartPanel(chart);
51
JFrame frame = new JFrame("Chart Example");
52
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
53
frame.add(chartPanel);
54
frame.pack();
55
frame.setVisible(true);
56

57
// Export as PNG
58
ChartUtils.saveChartAsPNG(new File("chart.png"), chart, 800, 600);
59
```
60

61
## Architecture
62

63
JFreeChart follows a structured architecture built around key components:
64

65
- **ChartFactory**: Factory methods for creating charts with default settings
66
- **JFreeChart**: Main chart container managing plots, titles, and legends
67
- **Plot**: Abstract base for different plot types (CategoryPlot, XYPlot, PiePlot)
68
- **Renderer**: Controls how data is visually represented (bars, lines, shapes, etc.)
69
- **Dataset**: Data model interfaces for different chart types
70
- **Axis**: Manages coordinate systems and labels for plots
71

72
This design enables extensive customization while providing simple factory methods for common use cases. Charts can be displayed in Swing/JavaFX applications, exported to various image formats, or rendered server-side for web applications.
73

74
## Capabilities
75

76
### Chart Creation
77

78
Factory methods for creating all major chart types with sensible defaults. Supports pie charts, bar charts, line charts, area charts, XY plots, time series, and specialized financial charts.
79

80
```java { .api }
81
// Pie Charts
82
public static JFreeChart createPieChart(String title, PieDataset dataset, boolean legend, boolean tooltips, boolean urls);
83
public static JFreeChart createRingChart(String title, PieDataset dataset, boolean legend, boolean tooltips, boolean urls);
84
public static JFreeChart createMultiplePieChart(String title, CategoryDataset dataset, TableOrder order, boolean legend, boolean tooltips, boolean urls);
85

86
// Bar Charts  
87
public static JFreeChart createBarChart(String title, String categoryAxisLabel, String valueAxisLabel, CategoryDataset dataset);
88
public static JFreeChart createBarChart(String title, String categoryAxisLabel, String valueAxisLabel, CategoryDataset dataset, PlotOrientation orientation, boolean legend, boolean tooltips, boolean urls);
89
public static JFreeChart createStackedBarChart(String title, String domainAxisLabel, String rangeAxisLabel, CategoryDataset dataset);
90
public static JFreeChart createWaterfallChart(String title, String categoryAxisLabel, String valueAxisLabel, CategoryDataset dataset, PlotOrientation orientation, boolean legend, boolean tooltips, boolean urls);
91

92
// Area Charts
93
public static JFreeChart createAreaChart(String title, String categoryAxisLabel, String valueAxisLabel, CategoryDataset dataset);
94
public static JFreeChart createStackedAreaChart(String title, String categoryAxisLabel, String valueAxisLabel, CategoryDataset dataset);
95

96
// Line Charts
97
public static JFreeChart createLineChart(String title, String categoryAxisLabel, String valueAxisLabel, CategoryDataset dataset);
98
public static JFreeChart createTimeSeriesChart(String title, String timeAxisLabel, String valueAxisLabel, XYDataset dataset);
99

100
// XY Charts
101
public static JFreeChart createScatterPlot(String title, String xAxisLabel, String yAxisLabel, XYDataset dataset);
102
public static JFreeChart createXYLineChart(String title, String xAxisLabel, String yAxisLabel, XYDataset dataset);
103
public static JFreeChart createXYAreaChart(String title, String xAxisLabel, String yAxisLabel, XYDataset dataset);
104
public static JFreeChart createStackedXYAreaChart(String title, String xAxisLabel, String yAxisLabel, TableXYDataset dataset);
105
public static JFreeChart createXYStepChart(String title, String xAxisLabel, String yAxisLabel, XYDataset dataset);
106
public static JFreeChart createXYStepAreaChart(String title, String xAxisLabel, String yAxisLabel, XYDataset dataset);
107
public static JFreeChart createXYBarChart(String title, String xAxisLabel, String yAxisLabel, IntervalXYDataset dataset, PlotOrientation orientation, boolean legend, boolean tooltips, boolean urls);
108
public static JFreeChart createBubbleChart(String title, String xAxisLabel, String yAxisLabel, XYZDataset dataset, PlotOrientation orientation, boolean legend, boolean tooltips, boolean urls);
109

110
// Statistical Charts
111
public static JFreeChart createHistogram(String title, String xAxisLabel, String yAxisLabel, IntervalXYDataset dataset, PlotOrientation orientation, boolean legend, boolean tooltips, boolean urls);
112
public static JFreeChart createBoxAndWhiskerChart(String title, String categoryAxisLabel, String valueAxisLabel, BoxAndWhiskerCategoryDataset dataset, boolean legend);
113
public static JFreeChart createBoxAndWhiskerChart(String title, String timeAxisLabel, String valueAxisLabel, BoxAndWhiskerXYDataset dataset, boolean legend);
114

115
// Financial Charts
116
public static JFreeChart createCandlestickChart(String title, String timeAxisLabel, String valueAxisLabel, OHLCDataset dataset, boolean legend);
117
public static JFreeChart createHighLowChart(String title, String timeAxisLabel, String valueAxisLabel, OHLCDataset dataset, boolean legend);
118

119
// Specialized Charts
120
public static JFreeChart createGanttChart(String title, String categoryAxisLabel, String dateAxisLabel, IntervalCategoryDataset dataset, boolean legend, boolean tooltips, boolean urls);
121
public static JFreeChart createPolarChart(String title, XYDataset dataset, boolean legend, boolean tooltips);
122
public static JFreeChart createWindPlot(String title, String xAxisLabel, String yAxisLabel, WindDataset dataset, boolean legend, boolean tooltips, boolean urls);
123
public static JFreeChart createWaferMapChart(String title, WaferMapDataset dataset, PlotOrientation orientation, boolean legend, boolean tooltips, boolean urls);
124
```
125

126
[Chart Creation](./chart-creation.md)
127

128
### Plots and Customization
129

130
Plot management and customization for controlling visual appearance, axes, renderers, and plot-specific features. Includes support for markers, annotations, and complex multi-dataset plots.
131

132
```java { .api }
133
// CategoryPlot - for bar charts, line charts
134
public CategoryDataset getDataset();
135
public void setDataset(CategoryDataset dataset);
136
public CategoryAxis getDomainAxis();
137
public void setDomainAxis(CategoryAxis axis);
138
public ValueAxis getRangeAxis();
139
public void setRangeAxis(ValueAxis axis);
140
public CategoryItemRenderer getRenderer();
141
public void setRenderer(CategoryItemRenderer renderer);
142

143
// XYPlot - for scatter plots, time series
144
public XYDataset getDataset();
145
public void setDataset(XYDataset dataset);
146
public ValueAxis getDomainAxis();
147
public void setDomainAxis(ValueAxis axis);
148
public ValueAxis getRangeAxis();
149
public void setRangeAxis(ValueAxis axis);
150
public XYItemRenderer getRenderer();
151
public void setRenderer(XYItemRenderer renderer);
152

153
// PiePlot - for pie charts
154
public PieDataset getDataset();
155
public void setDataset(PieDataset dataset);
156
public Paint getSectionPaint(Comparable key);
157
public void setSectionPaint(Comparable key, Paint paint);
158
```
159

160
[Plots and Customization](./plots-customization.md)
161

162
### Data Management
163

164
Dataset interfaces and implementations for providing data to charts. Supports category data, XY data, time series data, and specialized datasets for financial and statistical charts.
165

166
```java { .api }
167
// Category Data
168
public interface CategoryDataset extends KeyedValues2D, Dataset {
169
    public Number getValue(int row, int column);
170
    public Number getValue(Comparable rowKey, Comparable columnKey);
171
    public int getRowCount();
172
    public int getColumnCount();
173
    public Comparable getRowKey(int row);
174
    public Comparable getColumnKey(int column);
175
}
176

177
// XY Data
178
public interface XYDataset extends SeriesDataset {
179
    public int getItemCount(int series);
180
    public Number getX(int series, int item);
181
    public Number getY(int series, int item);
182
    public double getXValue(int series, int item);
183
    public double getYValue(int series, int item);
184
}
185

186
// Time Series
187
public class TimeSeries implements Cloneable, Serializable {
188
    public void add(RegularTimePeriod period, Number value);
189
    public void addOrUpdate(RegularTimePeriod period, Number value);
190
    public TimeSeriesDataItem getDataItem(RegularTimePeriod period);
191
    public int getItemCount();
192
}
193
```
194

195
[Data Management](./data-management.md)
196

197
### Rendering and Styling
198

199
Renderer interfaces and implementations that control how data is visually represented. Includes customization of colors, shapes, strokes, labels, and tooltips.
200

201
```java { .api }
202
// Category Renderers
203
public interface CategoryItemRenderer extends LegendItemSource {
204
    public void drawItem(Graphics2D g2, CategoryItemRendererState state, Rectangle2D dataArea, CategoryPlot plot, CategoryAxis domainAxis, ValueAxis rangeAxis, CategoryDataset dataset, int row, int column, int pass);
205
    public Paint getItemPaint(int row, int column);
206
    public void setSeriesPaint(int series, Paint paint);
207
    public Stroke getItemStroke(int row, int column);
208
    public void setSeriesStroke(int series, Stroke stroke);
209
}
210

211
// XY Renderers  
212
public interface XYItemRenderer extends LegendItemSource {
213
    public void drawItem(Graphics2D g2, XYItemRendererState state, Rectangle2D dataArea, PlotRenderingInfo info, XYPlot plot, ValueAxis domainAxis, ValueAxis rangeAxis, XYDataset dataset, int series, int item, CrosshairState crosshairState, int pass);
214
    public Paint getItemPaint(int series, int item);
215
    public void setSeriesPaint(int series, Paint paint);
216
    public Shape getItemShape(int series, int item);
217
    public void setSeriesShape(int series, Shape shape);
218
}
219
```
220

221
[Rendering and Styling](./rendering-styling.md)
222

223
### Axes and Scales
224

225
Axis management for controlling coordinate systems, labels, tick marks, and value ranges. Supports numeric, date/time, category, and logarithmic axes.
226

227
```java { .api }
228
// Value Axes (numeric, date)
229
public abstract class ValueAxis extends Axis {
230
    public Range getRange();
231
    public void setRange(Range range);
232
    public void setRange(double lower, double upper);
233
    public boolean isAutoRange();
234
    public void setAutoRange(boolean auto);
235
    public boolean isInverted();
236
    public void setInverted(boolean inverted);
237
}
238

239
// Category Axis
240
public class CategoryAxis extends Axis {
241
    public double getCategoryMargin();
242
    public void setCategoryMargin(double margin);
243
    public CategoryLabelPositions getCategoryLabelPositions();
244
    public void setCategoryLabelPositions(CategoryLabelPositions positions);
245
    public int getMaximumCategoryLabelLines();
246
    public void setMaximumCategoryLabelLines(int lines);
247
}
248

249
// Number Axis
250
public class NumberAxis extends ValueAxis {
251
    public NumberFormat getNumberFormatOverride();
252
    public void setNumberFormatOverride(NumberFormat formatter);
253
    public boolean isAutoRangeIncludesZero();
254
    public void setAutoRangeIncludesZero(boolean flag);
255
}
256

257
// Date Axis
258
public class DateAxis extends ValueAxis {
259
    public Date getMinimumDate();
260
    public void setMinimumDate(Date date);
261
    public Date getMaximumDate();
262
    public void setMaximumDate(Date date);
263
    public DateFormat getDateFormatOverride();
264
    public void setDateFormatOverride(DateFormat formatter);
265
}
266
```
267

268
[Axes and Scales](./axes-scales.md)
269

270
### Export and Display
271

272
Utilities for displaying charts in GUI applications and exporting to various image formats. Includes Swing integration and image generation capabilities.
273

274
```java { .api }
275
// Chart Display (Swing)
276
public class ChartPanel extends JPanel implements ChartChangeListener, ChartProgressListener {
277
    public ChartPanel(JFreeChart chart);
278
    public JFreeChart getChart();
279
    public void setChart(JFreeChart chart);
280
    public boolean isDomainZoomable();
281
    public void setDomainZoomable(boolean zoomable);
282
    public boolean isRangeZoomable();
283
    public void setRangeZoomable(boolean zoomable);
284
}
285

286
// Chart Export
287
public abstract class ChartUtils {
288
    public static void saveChartAsPNG(File file, JFreeChart chart, int width, int height);
289
    public static void saveChartAsJPEG(File file, JFreeChart chart, int width, int height);
290
    public static void writeChartAsPNG(OutputStream out, JFreeChart chart, int width, int height);
291
    public static void writeChartAsJPEG(OutputStream out, JFreeChart chart, int width, int height);
292
    public static void writeImageMap(PrintWriter writer, String name, ChartRenderingInfo info);
293
    public static String getImageMap(String name, ChartRenderingInfo info);
294
}
295
```
296

297
[Export and Display](./export-display.md)
298

299
### Labels, Tooltips, and Legends
300

301
Label generation, tooltip creation, and legend management for enhancing chart interactivity and readability.
302

303
```java { .api }
304
// Label Generators
305
public interface CategoryItemLabelGenerator {
306
    public String generateLabel(CategoryDataset dataset, int row, int column);
307
}
308

309
public interface XYItemLabelGenerator {
310
    public String generateLabel(XYDataset dataset, int series, int item);
311
}
312

313
public interface PieSectionLabelGenerator {
314
    public String generateSectionLabel(PieDataset dataset, Comparable key);
315
}
316

317
// Tooltip Generators
318
public interface CategoryToolTipGenerator {
319
    public String generateToolTip(CategoryDataset dataset, int row, int column);
320
}
321

322
public interface XYToolTipGenerator {
323
    public String generateToolTip(XYDataset dataset, int series, int item);
324
}
325

326
// Legend Management
327
public class LegendTitle extends Title {
328
    public LegendTitle(LegendItemSource source);
329
    public LegendItemSource[] getSources();
330
    public void setSources(LegendItemSource[] sources);
331
}
332
```
333

334
[Labels, Tooltips, and Legends](./labels-tooltips-legends.md)
335

336
## Types
337

338
```java { .api }
339
// Core Types
340
public enum PlotOrientation { HORIZONTAL, VERTICAL }
341
public enum Layer { FOREGROUND, BACKGROUND }
342

343
// Data Interfaces
344
public interface Dataset {
345
    public void addChangeListener(DatasetChangeListener listener);
346
    public void removeChangeListener(DatasetChangeListener listener);
347
    public DatasetGroup getGroup();
348
    public void setGroup(DatasetGroup group);
349
}
350

351
public interface SeriesDataset extends Dataset {
352
    public int getSeriesCount();
353
    public Comparable getSeriesKey(int series);
354
    public int indexOf(Comparable seriesKey);
355
}
356

357
// Specialized Dataset Interfaces
358
public interface IntervalXYDataset extends XYDataset {
359
    public Number getStartX(int series, int item);
360
    public Number getEndX(int series, int item);
361
    public Number getStartY(int series, int item); 
362
    public Number getEndY(int series, int item);
363
}
364

365
public interface IntervalCategoryDataset extends CategoryDataset {
366
    public Number getStartValue(int row, int column);
367
    public Number getStartValue(Comparable rowKey, Comparable columnKey);
368
    public Number getEndValue(int row, int column);
369
    public Number getEndValue(Comparable rowKey, Comparable columnKey);
370
}
371

372
public interface TableXYDataset extends XYDataset {
373
    public int getItemCount();
374
    public Number getX(int item);
375
    public Number getY(int series, int item);
376
}
377

378
public interface XYZDataset extends XYDataset {
379
    public Number getZ(int series, int item);
380
    public double getZValue(int series, int item);
381
}
382

383
public interface OHLCDataset extends XYDataset {
384
    public Number getHigh(int series, int item);
385
    public double getHighValue(int series, int item);
386
    public Number getLow(int series, int item);
387
    public double getLowValue(int series, int item);
388
    public Number getOpen(int series, int item);
389
    public double getOpenValue(int series, int item);
390
    public Number getClose(int series, int item);
391
    public double getCloseValue(int series, int item);
392
    public Number getVolume(int series, int item);
393
    public double getVolumeValue(int series, int item);
394
}
395

396
public interface BoxAndWhiskerCategoryDataset extends CategoryDataset {
397
    public Number getMean(int row, int column);
398
    public Number getMean(Comparable rowKey, Comparable columnKey);
399
    public Number getMedian(int row, int column);
400
    public Number getMedian(Comparable rowKey, Comparable columnKey);
401
    public Number getQ1(int row, int column);
402
    public Number getQ1(Comparable rowKey, Comparable columnKey);
403
    public Number getQ3(int row, int column);
404
    public Number getQ3(Comparable rowKey, Comparable columnKey);
405
}
406

407
public interface BoxAndWhiskerXYDataset extends XYDataset {
408
    public Number getMean(int series, int item);
409
    public Number getMedian(int series, int item);
410
    public Number getQ1(int series, int item);
411
    public Number getQ3(int series, int item);
412
    public Number getMinRegularValue(int series, int item);
413
    public Number getMaxRegularValue(int series, int item);
414
    public Number getMinOutlier(int series, int item);
415
    public Number getMaxOutlier(int series, int item);
416
    public List getOutliers(int series, int item);
417
}
418

419
public interface WindDataset extends XYDataset {
420
    public Number getWindDirection(int series, int item);
421
    public double getWindDirectionValue(int series, int item);
422
    public Number getWindForce(int series, int item);
423
    public double getWindForceValue(int series, int item);
424
}
425

426
public interface WaferMapDataset extends Dataset {
427
    public Number getChipValue(int chipx, int chipy);
428
    public int getMaxChipX();
429
    public int getMaxChipY();
430
    public Double getChipValue(Integer chipx, Integer chipy);
431
}
432

433
// Enums
434
public enum TableOrder { BY_ROW, BY_COLUMN }
435

436
// Event Handling
437
public interface ChangeListener extends EventListener {}
438
public interface ChartChangeListener extends EventListener {
439
    public void chartChanged(ChartChangeEvent event);
440
}
441
public interface ChartMouseListener extends EventListener {
442
    public void chartMouseClicked(ChartMouseEvent event);
443
    public void chartMouseMoved(ChartMouseEvent event);
444
}
445

446
// UI Types
447
public class RectangleInsets implements Serializable {
448
    public RectangleInsets(double top, double left, double bottom, double right);
449
    public double getTop();
450
    public double getLeft();
451
    public double getBottom();
452
    public double getRight();
453
}
454
```