* JFreeChart : a free chart library for the Java(tm) platform

* ===========================================================

*

* (C) Copyright 2000-2004, by Object Refinery Limited and Contributors.

*

* Project Info:  http://www.jfree.org/jfreechart/index.html

*

* This library is free software; you can redistribute it and/or modify it under the terms

* of the GNU Lesser General Public License as published by the Free Software Foundation;

* either version 2.1 of the License, or (at your option) any later version.

*

* This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;

* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

* See the GNU Lesser General Public License for more details.

*

* You should have received a copy of the GNU Lesser General Public License along with this

* library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,

* Boston, MA 02111-1307, USA.

*

* [Java is a trademark or registered trademark of Sun Microsystems, Inc.

* in the United States and other countries.]

*

* -----------------

* ChartFactory.java

* -----------------

* (C) Copyright 2001-2004, by Object Refinery Limited and Contributors.

*

* Original Author:  David Gilbert (for Object Refinery Limited);

* Contributor(s):   Serge V. Grachov;

*                   Joao Guilherme Del Valle;

*                   Bill Kelemen;

*                   Jon Iles;

*                   Jelai Wang;

*                   Richard Atkinson;

*                   David Browning (for Australian Institute of Marine Science);

*                   Benoit Xhenseval;

*

* $Id: ChartFactory.java,v 1.2 2004/09/08 09:14:03 mungady Exp $

*

* Changes

* -------

* 19-Oct-2001 : Version 1, most methods transferred from JFreeChart.java (DG);

* 22-Oct-2001 : Added methods to create stacked bar charts (DG);

*               Renamed DataSource.java --> Dataset.java etc. (DG);

* 31-Oct-2001 : Added 3D-effect vertical bar and stacked-bar charts, contributed by

*               Serge V. Grachov (DG);

* 07-Nov-2001 : Added a flag to control whether or not a legend is added to the chart (DG);

* 17-Nov-2001 : For pie chart, changed dataset from CategoryDataset to PieDataset (DG);

* 30-Nov-2001 : Removed try/catch handlers from chart creation, as the exception are now

*               RuntimeExceptions, as suggested by Joao Guilherme Del Valle (DG);

* 06-Dec-2001 : Added createCombinableXXXXXCharts methods (BK);

* 12-Dec-2001 : Added createCandlestickChart(...) method (DG);

* 13-Dec-2001 : Updated methods for charts with new renderers (DG);

* 08-Jan-2002 : Added import for com.jrefinery.chart.combination.CombinedChart (DG);

* 31-Jan-2002 : Changed the createCombinableVerticalXYBarChart(...) method to use renderer (DG);

* 06-Feb-2002 : Added new method createWindPlot(...) (DG);

* 23-Apr-2002 : Updates to the chart and plot constructor API (DG);

* 21-May-2002 : Added new method createAreaChart(...) (JI);

* 06-Jun-2002 : Added new method createGanttChart(...) (DG);

* 11-Jun-2002 : Renamed createHorizontalStackedBarChart() --> createStackedHorizontalBarChart() for

*               consistency (DG);

* 06-Aug-2002 : Updated Javadoc comments (DG);

* 21-Aug-2002 : Added createPieChart(CategoryDataset) method (DG);

* 02-Oct-2002 : Fixed errors reported by Checkstyle (DG);

* 09-Oct-2002 : Added methods including tooltips and URL flags (DG);

* 06-Nov-2002 : Moved renderers into a separate package (DG);

* 18-Nov-2002 : Changed CategoryDataset to TableDataset (DG);

* 21-Mar-2003 : Incorporated HorizontalCategoryAxis3D, see bug id 685501 (DG);

* 13-May-2003 : Merged some horizontal and vertical methods (DG);

* 24-May-2003 : Added support for timeline in createHighLowChart (BK);

* 07-Jul-2003 : Added createHistogram(...) method contributed by Jelai Wang (DG);

* 27-Jul-2003 : Added createStackedAreaXYChart(...) method (RA);

* 05-Aug-2003 : added new method createBoxAndWhiskerChart (DB);

* 08-Sep-2003 : Changed ValueAxis API (DG);

* 07-Oct-2003 : Added stepped area XY chart contributed by Matthias Rose (DG);

* 06-Nov-2003 : Added createWaterfallChart(...) method (DG);

* 20-Nov-2003 : Set rendering order for 3D bar charts to fix overlapping problems (DG);

* 25-Nov-2003 : Added createWaferMapChart(...) method (DG);

* 23-Dec-2003 : Renamed createPie3DChart() --> createPieChart3D for consistency (DG);

* 20-Jan-2004 : Added createPolarChart(...) method (DG);

* 28-Jan-2004 : Fixed bug (882890) with axis range in createStackedXYAreaChart() method (DG);

* 25-Feb-2004 : Renamed XYToolTipGenerator --> XYItemLabelGenerator (DG);

* 11-Mar-2004 : Updated for pie chart changes (DG);

* 27-Apr-2004 : Added new createPieChart() method contributed by Benoit Xhenseval (see RFE

*               942195) (DG);

* 11-May-2004 : Split StandardCategoryItemLabelGenerator --> StandardCategoryToolTipGenerator and

*               StandardCategoryLabelGenerator (DG);

*

*/

* A collection of utility methods for creating some standard charts with JFreeChart.

*/

    /**

     * Creates a pie chart with default settings.

     * <P>

     * The chart object returned by this method uses a {@link PiePlot} instance as the

     * plot.

     * @param title  the chart title (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A pie chart.

     */

    public static JFreeChart createPieChart(String title,

                                            PieDataset dataset,

                                            boolean legend,

                                            boolean tooltips,

                                            boolean urls) {

        PiePlot plot = new PiePlot(dataset);

        plot.setLabelGenerator(new StandardPieItemLabelGenerator());

        plot.setInsets(new Insets(0, 5, 5, 5));

        if (tooltips) {

            plot.setToolTipGenerator(

                new StandardPieItemLabelGenerator(

                    StandardPieItemLabelGenerator.DEFAULT_SECTION_LABEL_FORMAT

                )

            );

        }

        if (urls) {

            plot.setURLGenerator(new StandardPieURLGenerator());

        }

        return new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

    }

    /**

     * Creates a pie chart with default settings that compares 2 datasets.  The colour of each

     * section will be determined by the move from the value for the same key in previousDataset.

     * ie if value1 > value2 then the section will be in green (unless greenForIncrease is false,

     * in which case it would be red).  Each section can have a shade of red or green

     * as the difference can be taylored between 0% (black) and percentDiffForMaxScale% (bright

     * red/green).

     * <p>for instance is percentDiffForMaxScale is 10 (10%), a difference of 5% will have a half

     * shade of red/green, a difference of 10% or more will have a maximum shade/brightness of

     * red/green.

     * <P>

     * The chart object returned by this method uses a {@link PiePlot} instance as the

     * plot.

     * <p>

     * Written by <a href="mailto:opensource@objectlab.co.uk">Benoit Xhenseval</a>.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param previousDataset  the dataset for the last run, this will be used to compare each

     *                         Key in the dataset

     * @param percentDiffForMaxScale scale goes from bright red/green to black,

     *                               percentDiffForMaxScale indicate the change required to reach

     *                               top scale.

     * @param greenForIncrease  an increase since previousDataset will be displayed in green

     *                         (decrease red) if true

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     * @param subTitle displays a subtitle with colour scheme if true

     * @param showDifference  create a new dataset that will show the % difference between

     *                        the two datasets.

     *

     * @return A pie chart.

     * @since 0.9.18

     */

    public static JFreeChart createPieChart(String title,

                                            PieDataset dataset,

                                            PieDataset previousDataset,

                                            int percentDiffForMaxScale,

                                            boolean greenForIncrease,

                                            boolean legend,

                                            boolean tooltips,

                                            boolean urls,

                                            boolean subTitle,

                                            boolean showDifference) {

        PiePlot plot = new PiePlot(dataset);

        plot.setLabelGenerator(new StandardPieItemLabelGenerator());

        plot.setInsets(new Insets(0, 5, 5, 5));

        if (tooltips) {

            plot.setToolTipGenerator(

                new StandardPieItemLabelGenerator(

                    StandardPieItemLabelGenerator.DEFAULT_SECTION_LABEL_FORMAT

                )

            );

        }

        if (urls) {

            plot.setURLGenerator(new StandardPieURLGenerator());

        }

        List keys = dataset.getKeys();

        DefaultPieDataset series = null;

        if (showDifference) {

            series = new DefaultPieDataset();

        }

        final double colorPerPercent = 255.0 / percentDiffForMaxScale;

        for (Iterator it = keys.iterator(); it.hasNext();) {

            Comparable key = (Comparable) it.next();

            Number newValue = dataset.getValue(key);

            Number oldValue = previousDataset.getValue(key);

            int section = dataset.getIndex(key);

            if (oldValue == null) {

                if (greenForIncrease) {

                    plot.setSectionPaint(section, Color.green);

                }

                else {

                    plot.setSectionPaint(section, Color.red);

                }

                if (showDifference) {

                    series.setValue(key + " (+100%)", newValue);

                }

            }

            else {

                double percentChange = (newValue.doubleValue() / oldValue.doubleValue()

                                             - 1.0) * 100.0;

                double shade = (Math.abs(percentChange) >= percentDiffForMaxScale ? 255

                    : Math.abs(percentChange) * colorPerPercent);

                if (greenForIncrease && newValue.doubleValue() > oldValue.doubleValue()

                || !greenForIncrease && newValue.doubleValue() < oldValue.doubleValue()) {

                    plot.setSectionPaint(section, new Color(0, (int) shade, 0));

                }

                else {

                    plot.setSectionPaint(section, new Color((int) shade, 0, 0));

                }

                if (showDifference) {

                    series.setValue(

                        key + " (" + (percentChange >= 0 ? "+" : "")

                        + NumberFormat.getPercentInstance().format(percentChange / 100.0)

                        + ")", newValue

                    );

                }

            }

        }

        if (showDifference) {

            plot.setDataset(series);

        }

        JFreeChart chart =  new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        if (subTitle) {

            TextTitle subtitle = null;

            subtitle = new TextTitle("Bright " + (greenForIncrease ? "red" : "green")

                    + "=change >=-" + percentDiffForMaxScale + "%, Bright "

                    + (!greenForIncrease ? "red" : "green") + "=change >=+"

                    + percentDiffForMaxScale + "%", new Font("SansSerif", Font.PLAIN, 10));

            chart.addSubtitle(subtitle);

        }

        return chart;

    }

    /**

     * Creates a chart that displays multiple pie plots.

     * <P>

     * The chart object returned by this method uses a {@link MultiplePiePlot} instance as the

     * plot.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param dataset  the dataset (<code>null</code> permitted).

     * @param order  the order that the data is extracted (by row or by column) (<code>null</code>

     *               not permitted).

     * @param legend  include a legend?

     * @param tooltips  generate tooltips?

     * @param urls  generate URLs?

     *

     * @return A chart.

     */

    public static JFreeChart createMultiplePieChart(String title,

                                                    CategoryDataset dataset,

                                                    TableOrder order,

                                                    boolean legend,

                                                    boolean tooltips,

                                                    boolean urls) {

        if (order == null) {

            throw new IllegalArgumentException("Null 'order' argument.");

        }

        MultiplePiePlot plot = new MultiplePiePlot(dataset);

        plot.setDataExtractOrder(order);

        plot.setBackgroundPaint(null);

        plot.setOutlineStroke(null);

        if (tooltips) {

            PieToolTipGenerator tooltipGenerator = new StandardPieItemLabelGenerator();

            PiePlot pp = (PiePlot) plot.getPieChart().getPlot();

            pp.setToolTipGenerator(tooltipGenerator);

        }

        if (urls) {

            PieURLGenerator urlGenerator = new StandardPieURLGenerator();

            PiePlot pp = (PiePlot) plot.getPieChart().getPlot();

            pp.setURLGenerator(urlGenerator);

        }

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a 3D pie chart using the specified dataset.

     * <P>

     * The chart object returned by this method uses a {@link PiePlot3D} instance as the

     * plot.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A pie chart.

     */

    public static JFreeChart createPieChart3D(String title,

                                              PieDataset dataset,

                                              boolean legend,

                                              boolean tooltips,

                                              boolean urls) {

        PiePlot3D plot = new PiePlot3D(dataset);

        plot.setInsets(new Insets(0, 5, 5, 5));

        if (tooltips) {

            plot.setToolTipGenerator(new StandardPieItemLabelGenerator());

        }

        if (urls) {

            plot.setURLGenerator(new StandardPieURLGenerator());

        }

        return new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

    }

    /**

     * Creates a chart that displays multiple pie plots.

     * <P>

     * The chart object returned by this method uses a {@link MultiplePiePlot} instance as the

     * plot.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param dataset  the dataset (<code>null</code> permitted).

     * @param order  the order that the data is extracted (by row or by column) (<code>null</code>

     *               not permitted).

     * @param legend  include a legend?

     * @param tooltips  generate tooltips?

     * @param urls  generate URLs?

     *

     * @return a chart.

     */

    public static JFreeChart createMultiplePieChart3D(String title,

                                                      CategoryDataset dataset,

                                                      TableOrder order,

                                                      boolean legend,

                                                      boolean tooltips,

                                                      boolean urls) {

        if (order == null) {

            throw new IllegalArgumentException("Null 'order' argument.");

        }

        MultiplePiePlot plot = new MultiplePiePlot(dataset);

        plot.setDataExtractOrder(order);

        plot.setBackgroundPaint(null);

        plot.setOutlineStroke(null);

        JFreeChart pieChart = new JFreeChart(new PiePlot3D(null));

        TextTitle seriesTitle = new TextTitle("Series Title", new Font("SansSerif", Font.BOLD, 12));

        seriesTitle.setPosition(RectangleEdge.BOTTOM);

        pieChart.setTitle(seriesTitle);

        pieChart.setBackgroundPaint(null);

        plot.setPieChart(pieChart);

        if (tooltips) {

            PieToolTipGenerator tooltipGenerator = new StandardPieItemLabelGenerator();

            PiePlot pp = (PiePlot) plot.getPieChart().getPlot();

            pp.setToolTipGenerator(tooltipGenerator);

        }

        if (urls) {

            PieURLGenerator urlGenerator = new StandardPieURLGenerator();

            PiePlot pp = (PiePlot) plot.getPieChart().getPlot();

            pp.setURLGenerator(urlGenerator);

        }

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a bar chart.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link BarRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (horizontal or vertical) (<code>null</code> not

     *                     permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A bar chart.

     */

    public static JFreeChart createBarChart(String title,

                                            String categoryAxisLabel,

                                            String valueAxisLabel,

                                            CategoryDataset dataset,

                                            PlotOrientation orientation,

                                            boolean legend,

                                            boolean tooltips,

                                            boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel);

        ValueAxis valueAxis = new NumberAxis(valueAxisLabel);

        BarRenderer renderer = new BarRenderer();

        if (orientation == PlotOrientation.HORIZONTAL) {

            ItemLabelPosition position1 = new ItemLabelPosition(

                ItemLabelAnchor.OUTSIDE3, TextAnchor.CENTER_LEFT

            );

            renderer.setPositiveItemLabelPosition(position1);

            ItemLabelPosition position2 = new ItemLabelPosition(

                ItemLabelAnchor.OUTSIDE9, TextAnchor.CENTER_RIGHT

            );

            renderer.setNegativeItemLabelPosition(position2);

         }

        else if (orientation == PlotOrientation.VERTICAL) {

            ItemLabelPosition position1 = new ItemLabelPosition(

                ItemLabelAnchor.OUTSIDE12, TextAnchor.BOTTOM_CENTER

            );

            renderer.setPositiveItemLabelPosition(position1);

            ItemLabelPosition position2 = new ItemLabelPosition(

                ItemLabelAnchor.OUTSIDE6, TextAnchor.TOP_CENTER

            );

            renderer.setNegativeItemLabelPosition(position2);

        }

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a stacked bar chart with default settings.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link StackedBarRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param domainAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param rangeAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the orientation of the chart (horizontal or vertical) (<code>null</code>

     *                     not permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A stacked bar chart.

     */

    public static JFreeChart createStackedBarChart(String title,

                                                   String domainAxisLabel,

                                                   String rangeAxisLabel,

                                                   CategoryDataset dataset,

                                                   PlotOrientation orientation,

                                                   boolean legend,

                                                   boolean tooltips,

                                                   boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis(domainAxisLabel);

        ValueAxis valueAxis = new NumberAxis(rangeAxisLabel);

        StackedBarRenderer renderer = new StackedBarRenderer();

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a bar chart with a 3D effect.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis3D} for the domain axis, a {@link NumberAxis3D} as the

     * range axis, and a {@link BarRenderer3D} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (horizontal or vertical) (<code>null</code>

     *                     not permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A bar chart with a 3D effect.

     */

    public static JFreeChart createBarChart3D(String title,

                                              String categoryAxisLabel,

                                              String valueAxisLabel,

                                              CategoryDataset dataset,

                                              PlotOrientation orientation,

                                              boolean legend,

                                              boolean tooltips,

                                              boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis3D(categoryAxisLabel);

        ValueAxis valueAxis = new NumberAxis3D(valueAxisLabel);

        BarRenderer3D renderer = new BarRenderer3D();

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        if (orientation == PlotOrientation.HORIZONTAL) {

            // change rendering order to ensure that bar overlapping is the right way around

            plot.setRowRenderingOrder(SortOrder.DESCENDING);

            plot.setColumnRenderingOrder(SortOrder.DESCENDING);

        }

        plot.setForegroundAlpha(0.75f);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a stacked bar chart with a 3D effect and default settings.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis3D} for the domain axis, a {@link NumberAxis3D} as the

     * range axis, and a {@link StackedBarRenderer3D} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the orientation (horizontal or vertical) (<code>null</code> not

     *                     permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A stacked bar chart with a 3D effect.

     */

    public static JFreeChart createStackedBarChart3D(String title,

                                                     String categoryAxisLabel,

                                                     String valueAxisLabel,

                                                     CategoryDataset dataset,

                                                     PlotOrientation orientation,

                                                     boolean legend,

                                                     boolean tooltips,

                                                     boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis3D(categoryAxisLabel);

        ValueAxis valueAxis = new NumberAxis3D(valueAxisLabel);

        // create the renderer...

        CategoryItemRenderer renderer = new StackedBarRenderer3D();

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        // create the plot...

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        if (orientation == PlotOrientation.HORIZONTAL) {

            // change rendering order to ensure that bar overlapping is the right way around

            plot.setColumnRenderingOrder(SortOrder.DESCENDING);

        }

        // create the chart...

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates an area chart with default settings.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and an {@link AreaRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (<code>null</code> not permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return An area chart.

     */

    public static JFreeChart createAreaChart(String title,

                                             String categoryAxisLabel,

                                             String valueAxisLabel,

                                             CategoryDataset dataset,

                                             PlotOrientation orientation,

                                             boolean legend,

                                             boolean tooltips,

                                             boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel);

        categoryAxis.setCategoryMargin(0.0);

        ValueAxis valueAxis = new NumberAxis(valueAxisLabel);

        AreaRenderer renderer = new AreaRenderer();

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a stacked area chart with default settings.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link StackedAreaRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (horizontal or vertical) (<code>null</code> not

     *                     permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A stacked area chart.

     */

    public static JFreeChart createStackedAreaChart(String title,

                                                    String categoryAxisLabel,

                                                    String valueAxisLabel,

                                                    CategoryDataset dataset,

                                                    PlotOrientation orientation,

                                                    boolean legend,

                                                    boolean tooltips,

                                                    boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel);

        ValueAxis valueAxis = new NumberAxis(valueAxisLabel);

        StackedAreaRenderer renderer = new StackedAreaRenderer();

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a line chart with default settings.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link LineAndShapeRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the chart orientation (horizontal or vertical) (<code>null</code>

     *                     not permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A line chart.

     */

    public static JFreeChart createLineChart(String title,

                                             String categoryAxisLabel,

                                             String valueAxisLabel,

                                             CategoryDataset dataset,

                                             PlotOrientation orientation,

                                             boolean legend,

                                             boolean tooltips,

                                             boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel);

        ValueAxis valueAxis = new NumberAxis(valueAxisLabel);

        LineAndShapeRenderer renderer = new LineAndShapeRenderer();

        renderer.setDrawLines(true);

        renderer.setDrawShapes(false);

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardCategoryToolTipGenerator());

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a Gantt chart using the supplied attributes plus default values where required.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link DateAxis} as the

     * range axis, and a {@link GanttRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param dateAxisLabel  the label for the date axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A Gantt chart.

     */

    public static JFreeChart createGanttChart(String title,

                                              String categoryAxisLabel,

                                              String dateAxisLabel,

                                              IntervalCategoryDataset dataset,

                                              boolean legend,

                                              boolean tooltips,

                                              boolean urls) {

        CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel);

        DateAxis dateAxis = new DateAxis(dateAxisLabel);

        CategoryItemRenderer renderer = new GanttRenderer();

        if (tooltips) {

            renderer.setToolTipGenerator(

                new IntervalCategoryToolTipGenerator("{3} - {4}", DateFormat.getDateInstance())

            );

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, dateAxis, renderer);

        plot.setOrientation(PlotOrientation.HORIZONTAL);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a waterfall chart.

     * <P>

     * The chart object returned by this method uses a {@link CategoryPlot} instance as the

     * plot, with a {@link CategoryAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link WaterfallBarRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param categoryAxisLabel  the label for the category axis (<code>null</code> permitted).

     * @param valueAxisLabel  the label for the value axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (horizontal or vertical) (<code>null</code> NOT

     *                     permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A waterfall chart.

     */

    public static JFreeChart createWaterfallChart(String title,

                                                  String categoryAxisLabel,

                                                  String valueAxisLabel,

                                                  CategoryDataset dataset,

                                                  PlotOrientation orientation,

                                                  boolean legend,

                                                  boolean tooltips,

                                                  boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel);

        categoryAxis.setCategoryMargin(0.0);

        ValueAxis valueAxis = new NumberAxis(valueAxisLabel);

        WaterfallBarRenderer renderer = new WaterfallBarRenderer();

        if (orientation == PlotOrientation.HORIZONTAL) {

            ItemLabelPosition position = new ItemLabelPosition(

                ItemLabelAnchor.CENTER, TextAnchor.CENTER, TextAnchor.CENTER, Math.PI / 2.0

            );

            renderer.setPositiveItemLabelPosition(position);

            renderer.setNegativeItemLabelPosition(position);

         }

        else if (orientation == PlotOrientation.VERTICAL) {

            ItemLabelPosition position = new ItemLabelPosition(

                ItemLabelAnchor.CENTER, TextAnchor.CENTER, TextAnchor.CENTER, 0.0

            );

            renderer.setPositiveItemLabelPosition(position);

            renderer.setNegativeItemLabelPosition(position);

        }

        if (tooltips) {

            StandardCategoryToolTipGenerator generator = new StandardCategoryToolTipGenerator();

            renderer.setToolTipGenerator(generator);

        }

        if (urls) {

            renderer.setItemURLGenerator(new StandardCategoryURLGenerator());

        }

        CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valueAxis, renderer);

        plot.clearRangeMarkers();

        Marker baseline = new ValueMarker(0.0);

        baseline.setPaint(Color.black);

        plot.addRangeMarker(baseline, Layer.FOREGROUND);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a polar plot for the specified dataset (x-values interpreted as angles in degrees).

     * <P>

     * The chart object returned by this method uses a {@link PolarPlot} instance as the

     * plot, with a {@link NumberAxis} for the radial axis.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param dataset  the dataset (<code>null</code> permitted).

     * @param legend  legend required?

     * @param tooltips  tooltips required?

     * @param urls  URLs required?

     *

     * @return A chart.

     */

    public static JFreeChart createPolarChart(String title,

                                              XYDataset dataset,

                                              boolean legend,

                                              boolean tooltips,

                                              boolean urls) {

        PolarPlot plot = new PolarPlot();

        plot.setDataset(dataset);

        NumberAxis rangeAxis = new NumberAxis();

        rangeAxis.setAxisLineVisible(false);

        rangeAxis.setTickMarksVisible(false);

        rangeAxis.setTickLabelInsets(new Insets(0, 0, 0, 0));

        plot.setRadialAxis(rangeAxis);

        plot.setRenderer(new DefaultPolarItemRenderer());

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates a scatter plot with default settings.

     * <P>

     * The chart object returned by this method uses an {@link XYPlot} instance as the

     * plot, with a {@link NumberAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link StandardXYItemRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param xAxisLabel  a label for the X-axis (<code>null</code> permitted).

     * @param yAxisLabel  a label for the Y-axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (horizontal or vertical) (<code>null</code> NOT

     *                     permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return A scatter plot.

     */

    public static JFreeChart createScatterPlot(String title,

                                               String xAxisLabel,

                                               String yAxisLabel,

                                               XYDataset dataset,

                                               PlotOrientation orientation,

                                               boolean legend,

                                               boolean tooltips,

                                               boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        NumberAxis xAxis = new NumberAxis(xAxisLabel);

        xAxis.setAutoRangeIncludesZero(false);

        NumberAxis yAxis = new NumberAxis(yAxisLabel);

        yAxis.setAutoRangeIncludesZero(false);

        XYPlot plot = new XYPlot(dataset, xAxis, yAxis, null);

        XYToolTipGenerator toolTipGenerator = null;

        if (tooltips) {

            toolTipGenerator = new StandardXYToolTipGenerator();

        }

        XYURLGenerator urlGenerator = null;

        if (urls) {

            urlGenerator = new StandardXYURLGenerator();

        }

        StandardXYItemRenderer renderer = new StandardXYItemRenderer(

            StandardXYItemRenderer.SHAPES, toolTipGenerator, urlGenerator

        );

        renderer.setShapesFilled(Boolean.TRUE);

        plot.setRenderer(renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates and returns a default instance of an XY bar chart.

     * <P>

     * The chart object returned by this method uses an {@link XYPlot} instance as the

     * plot, with a {@link DateAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link XYBarRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param xAxisLabel  a label for the X-axis (<code>null</code> permitted).

     * @param dateAxis  make the domain axis display dates?

     * @param yAxisLabel  a label for the Y-axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the orientation (horizontal or vertical) (<code>null</code> NOT

     *                     permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return An XY bar chart.

     */

    public static JFreeChart createXYBarChart(String title,

                                              String xAxisLabel,

                                              boolean dateAxis,

                                              String yAxisLabel,

                                              IntervalXYDataset dataset,

                                              PlotOrientation orientation,

                                              boolean legend,

                                              boolean tooltips,

                                              boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        ValueAxis domainAxis = null;

        if (dateAxis) {

            domainAxis = new DateAxis(xAxisLabel);

        }

        else {

            NumberAxis axis = new NumberAxis(xAxisLabel);

            axis.setAutoRangeIncludesZero(false);

            domainAxis = axis;

        }

        ValueAxis valueAxis = new NumberAxis(yAxisLabel);

        XYBarRenderer renderer = new XYBarRenderer();

        if (tooltips) {

            renderer.setToolTipGenerator(new StandardXYToolTipGenerator());

        }

        if (urls) {

            renderer.setURLGenerator(new StandardXYURLGenerator());

        }

        XYPlot plot = new XYPlot(dataset, domainAxis, valueAxis, renderer);

        plot.setOrientation(orientation);

        JFreeChart chart = new JFreeChart(title, JFreeChart.DEFAULT_TITLE_FONT, plot, legend);

        return chart;

    }

    /**

     * Creates an area chart using an {@link XYDataset}.

     * <P>

     * The chart object returned by this method uses an {@link XYPlot} instance as the

     * plot, with a {@link NumberAxis} for the domain axis, a {@link NumberAxis} as the

     * range axis, and a {@link XYAreaRenderer} as the renderer.

     *

     * @param title  the chart title (<code>null</code> permitted).

     * @param xAxisLabel  a label for the X-axis (<code>null</code> permitted).

     * @param yAxisLabel  a label for the Y-axis (<code>null</code> permitted).

     * @param dataset  the dataset for the chart (<code>null</code> permitted).

     * @param orientation  the plot orientation (horizontal or vertical) (<code>null</code> NOT

     *                    permitted).

     * @param legend  a flag specifying whether or not a legend is required.

     * @param tooltips  configure chart to generate tool tips?

     * @param urls  configure chart to generate URLs?

     *

     * @return An XY area chart.

     */

    public static JFreeChart createXYAreaChart(String title,

                                               String xAxisLabel,

                                               String yAxisLabel,

                                               XYDataset dataset,

                                               PlotOrientation orientation,

                                               boolean legend,

                                               boolean tooltips,

                                               boolean urls) {

        if (orientation == null) {

            throw new IllegalArgumentException("Null 'orientation' argument.");

        }

        NumberAxis xAxis = new NumberAxis(xAxisLabel);