Roadmap...

Post by **david.gilbert** » Thu Aug 14, 2003 4:21 pm

First draft, comments welcome:

************************
*  JFREECHART ROADMAP  *
************************

Written by David Gilbert, JFreeChart Project Leader.

14 August 2003


INTRODUCTION 
------------
An increasing number of developers are asking me when JFreeChart 1.0 will be
released.  In the open source tradition, the definitive answer is, of course,
WHEN IT IS READY!  But although that answer is accurate, it isn't very
helpful.  

So, to be a little more informative, I've made the following notes of the
major items that I want to complete before JFreeChart is labelled with the
magical "1.0" version number.  This list is not set in concrete, but is
intended to give an indication of the work remaining to be done.

I welcome any feedback on the task list, particularly regarding anything that
I've left off.


A NOTE ON API CHANGES
---------------------
As I've said many times before, once version 1.0 is released, the JFreeChart
API will be frozen.  That, I'm sure, is what is motivating people to ask the
"when" question, particularly since the API changes have been significant over
the last few months (to recap, the horizontal/vertical class split was
eliminated, the item labelling mechanism changed, and support for multiple
axes was added, among other things).
  
Although there WILL be further API changes as the tasks outlined below are
completed, I don't foresee anything on the scale of what has been completed
recently.  I will @deprecate where possible, and document otherwise.  I accept
that the API changes haven't been well documented in past releases, but please
note that I'm under the same time pressures as everyone else...so no more hate
mail please!


MAJOR TASKS
-----------

[1]  Thread synchronisation

It should be possible to update a dataset in one thread, while one or more
charts are being redrawn in another thread.  Note that this is not as simple
as putting 'synchronised' keywords here and there - the chart makes multiple
calls to the dataset while drawing, and the dataset needs to be 'locked' from
updates for the duration of all the calls.  Ideally, datasets should be able
to queue updates while they are locked...I'm not sure how difficult that will
be to implement though.


[2]  Serialisation to/from XML

Provide read and write capability, in XML format, for charts and datasets.


[3]  Chart Property Editors

The existing property editors have had little revision since version 0.5.6.  I
need to ensure that all aspects of the charts can be customised via the
property editors.


[4]  Logarithmic Axes

Some alternative implementations for the LogarithmicAxis class have been
proposed.  I agree that there are some changes required - I haven't looked at
the detail yet, but I will.


[5]  Radar plots

Add support for radar plots.  These can most likely be made to work with the
existing CategoryDataset.


[6]  Enhance Chart Legends

I plan to convert the legend to a ChartTitle (so that it can be displayed
anywhere that a title can be displayed), plus provide a mechanism for multiple
legends per chart (to cover multiple axes and datasets).


[7]  Pie chart labelling enhancements

Add smarter code for generating pie chart labels avoiding overlapping.


[8]  ContourPlot

Tidy up the ContourPlot and ContourDataset code, perhaps getting closer
integration with the XYPlot class.


[9]  Eliminate MeterDataset

The MeterDataset interface returns a single value plus information about the
"normal", "warning" and "critical" ranges.  The ranges relate to presentation,
and should be moved to the chart/plot classes.  MeterDataset can then be
replaced by ValueDataset.


[10]  Item Labels

A lot of changes have been made to the code for generating and displaying item
labels.  There is some work remaining to tidy up this code.


[11]  Domain and Range Markers

Two enhancements are required.  First, the ability to highlight ranges in
addition to the current point values.  Second, an option to display markers
'in front' or 'behind' the chart data items.  



VERSION 2.0
-----------

The following will not make the 1.0 release:

[1]  3D charts

JFreeChart doesn't support "real" 3D charts, only some 3D effects on 2D
charts.  It is a frequent request, but this is such a big area that I have
decided to focus on getting the 2D charts right first.


UNDECIDED
---------

I haven't decided what to do with the following tasks yet...please feel free
to comment:

[1]  KeyPlot class

The CategoryPlot class uses keys (categories) for the domain axis and values
for the range axis.  A new plot class could generalise this to allow:

    -  keys for both axes;
    -  values for the domain axis and keys for the range axis;

In effect, this is what the existing symbolic charts (based on the XYPlot
class) do...but the implementation could be cleaner if it is done directly
rather than tacking on symbols to numerical values (which is a motivation for
doing this before 1.0).  
 

[2]  Specialised GanttPlot and GanttDataset

The existing Gantt chart has limitations that mostly arise from the use of the
CategoryDataset interface.  I think the best long term approach for the Gantt
charts will be to write a purpose-built dataset and plot class for these
charts.  This would be mostly new code and quite a big task (which is a
motivation for leaving this out of 1.0).


THE SCHEDULE
------------
You will notice that I haven't attached a date schedule to these tasks.  That
is because my ability to forecast:

    (a)  how much work is involved in each task;

    (b)  how much time I will be able to spend on development in the coming
         months;

    (c)  how much help I will receive from other developers;

...is so limited that any schedule would be a work of fiction.  That said, 
my guess is that a 1.0 release will occur in the first half of 2004.

Karthicks · Post by **Karthicks** » Mon Aug 18, 2003 6:49 am

Dear David ,
<b>comment regarding thread synchronization in JFreechart :<b>
In Java Design all ui related operations takes place in swing thread.
For example in java table design, Table UI access the table model in same swing thread. Similarly table model changes is expected to take place in swing Thread. If any application changes the table model other than the swing thread it is wrong coding in the application which uses table ui.
So any data model changes from thread other than swing thread has to be qued in swingthread (SwingUtilities.invokeLater(run)).

So I feel freechart does not worry about thread synchronization. It is responsibility of application which uses JFreeChart to ensure that chart draw operations and data model changes in SwingThread.

So please do provide your feedbacks,

S.Karthick

Post by **david.gilbert** » Mon Aug 18, 2003 8:51 am

Well, I guess that is something I'll have to consider...but wouldn't it be easier to use JFreeChart if you can assume that it is safe to update datasets in separate threads to the chart drawing?

askex2056 · Post by **askex2056** » Mon Aug 18, 2003 9:08 am

Hm, you would still have to implement something like the SwingUtilities.invokeLater() in JFreeChart. That would be the same, i think.
Here is the code of SwingUtilities.invokeLater():

Code: Select all

    public static void invokeLater(Runnable doRun) {
	EventQueue.invokeLater(doRun);
    }

of EventQueue.invokeLater:

Code: Select all

    public static void invokeLater(Runnable runnable) {
        Toolkit.getEventQueue().postEvent(
            new InvocationEvent(Toolkit.getDefaultToolkit(), runnable));
    }

of EventQueue.postEvent()

Code: Select all

    public void postEvent(AWTEvent theEvent) {
        SunToolkit.flushPendingEvents();
        postEventPrivate(theEvent);
    }

... so you are queuing events here as well, as it seems.

Karthicks · Post by **Karthicks** » Mon Aug 18, 2003 9:42 am

Dear David Gilbert,

It is ageneral guidelines in swing to update ui components data model in swing thread. Since freechart is a java based ui component bean I think there is no value to the freechart in adding swing thread handling with in the data model or ui component. It is violation of swing guidelines and it will end up in unnecessary complexity for JFreehchart.

For more details please do refer below link ,

"http://java.sun.com/docs/books/tutorial ... reads.html"

Thanks & Regards,
S.Karthick

Post by **david.gilbert** » Mon Aug 18, 2003 10:01 am

JFreeChart use isn't restricted to just Swing...you can use it in servlets, or in the background of an application generating reports (in, say, PDF format). I think thread safety is worth pursuing, although I won't know for sure until I start writing the code and get into the nitty-gritty.

tbardzil · Post by **tbardzil** » Fri Aug 22, 2003 3:42 am

How about allowing users to vote for feature requests via the forums?

Tim

arnaud · Post by **arnaud** » Wed Aug 27, 2003 6:57 pm

Hello,

2 remarks on the roadmap:

1) Item Labels:
As I needed this functionality on my project and it was not available at that time, I spent some time to make it work. I added a Request For Enhancement (RFE) on the sourceForge project page (more info on: Nice Visible Value Labels published on 2003-apr-12).

I see that you have incorporated a big part of it except the automatic calculation of the axis range. It is necessary to add this to JFreeChart : if the autorange property is true, it makes sure that the range is well adjusted so that any item label is truncated.It is not of great help to be able to display custom item labels and have the user not able to read them...

I propose to adapt the code I had written for the version 0.9.6 to the last version.
Do you agree to incorporate it to the next release (btw, you had set the priority of this RFE among the 4 highest tasks) ?

2) Internationalization:
I needed to translate all text displayed by JFreeChart into french and that was not an existing functionality so I wrote some code and added a dedidated RFE (more info on: Internationalization published on 2003-feb-20).

This forum shows there is a great number of developers who are not english native speaking and who certainly would appreciate to use this functionality.

I propose to adapt the code I had written for the version 0.9.6 to the last version and manage the different translations. Do you agree to incorporate this into the next release ?

Best regards,

Arnaud

Post by **david.gilbert** » Wed Aug 27, 2003 7:40 pm

Hi Arnaud,

Thanks for the feedback and the work you've done:

1) I've been meaning to incorporate the auto-range part of your code. I forget the details, but there was something in your implementation that I wanted to modify before incorporating it. I'll take another look soon and get it finished off.

2) Another task high on my priority list now is to completely rewrite the chart property editors. That will include localisation of the strings in the user interface...you could update your existing code if you wanted, but it might make more sense to wait for the revised property editors.

I think these things won't make it into the next release, but they will make it for 1.0.

arnaud · Post by **arnaud** » Thu Aug 28, 2003 4:43 pm

Hello David,

I understand your point of view and I do agree that the chart property editors needs to be completely rewritten.

As far as I'm concerned, I'll soon need to migrate from JFreeChart release 0.9.6 to a newer one (to benefit from the new features, bug fixes, ...). And of course, I cannot migrate with less features (actually my project, using JFC 0.9.6 and the additions I posted on RFEs works well with internationalization, and auto-range). My interest is to have the features "item labels auto-range" and internationalization released as soon as possible.

I also obviously do agree that JFreeChart schedule highly depends, as you've written, on :

(a) how much work is involved in each task;
(b) how much time you will be able to spend on development in the coming months;
(c) how much help you will receive from other developers;

As you pointed out on point c, the more help you get from other developers, the faster things will go. As my goal is to help things go faster I'm ready to provide help for that. For this purpose, I propose to work on "item labels auto-range" and internationalization (even if internationalization feature will later need a complete rewriting) and adapt them to current developement version. Will that be helpfull ? Is there other ways I can better help ?

Best regards,
Arnaud

Post by **david.gilbert** » Fri Aug 29, 2003 10:16 am

Hi Arnaud,

Thanks! If you update the internationalization code, I'll put it in as soon as you are done. You're obviously OK with the fact that it will need updating again as the property editors are rewritten.

For the item labels auto-range, I'd like to get that in as well, but I want to review your code again, because there was something that held me back from putting it straight in (of course, I should have e-mailed you about it while I was thinking about it - now I've forgotten what it was). If you want to speed up the process, then updating the code to work against the latest CVS would help me a lot...

Again, thanks for your help!

Dave.

arnaud · Post by **arnaud** » Fri Aug 29, 2003 11:08 am

Hello David,

Nice I can work it a way it helps you.

For internationalization, I plan to send something next week ; I'll manage to have a few people interested by providing some translation.

For item labels, my code was surely a little messy and you manage well to make it more general. I'll try now to rewrite the "auto-range" part to make it more clear and to explain the algorithm. I guess I'll be able to send something by september the 9th. Stay tuned ! Of course, I'm ready to answer all your questions if something is not clear.

Keep the good work.

Best regards,
Arnaud

mhilpert · Post by **mhilpert** » Wed Sep 03, 2003 4:43 pm

i would love to see an extended API for the JFreeChart class. when i started using JFreeChart, i concentrated on plots, axis, renderers ... and all got cluttered up. some weeks ago, i changed my view to the chart itself. i have tasks to "set teh color of the series" or "set the format of this axis", etc. I ended up writing a custom class that is a wrapper for the JFreeChart class which offers simple set() Methods and hide all the unnecessary (for the application developer) stuff to first get the plots, checks for specific instances, get renderers, special axes, etc.

The result is a single class (which I call JFreeChartGenerator) that offers a clean API with methods like:

setAxisLabel(JFreeChart chart, int axisId, String label)
setMaximumAxisValue(JFreeChart chart, int axisId, double value)
setSeriesColor(JFreeChart chart, int seriesIndex, Color color)
setTickMarksVisible(JFreeChart chart, int axisId, boolean state)
...
and lots more.

The methods itself care about the internal stuff of plots, renderers, axis, etc. Example of setSeriesColor():

Code: Select all

    /**
	 * Set color of series.
	 * 
	 * @param chart JFreeChart.
	 * @param seriesIndex Index of series to set color of (0 = first series)
	 * @param color New color to set.
	 */
	public void setSeriesColor(JFreeChart chart, int seriesIndex, Color color) {
        if (chart != null) {
            Plot plot = chart.getPlot();
            try {
                if (plot instanceof CategoryPlot) {
                    CategoryPlot categoryPlot = chart.getCategoryPlot();
                    CategoryItemRenderer cir = categoryPlot.getRenderer();
                    cir.setSeriesPaint(seriesIndex, color);
                } else if (plot instanceof PiePlot) {
                    PiePlot piePlot = (PiePlot) chart.getPlot();
                    piePlot.setPaint(seriesIndex, color);
                } else if (plot instanceof XYPlot) {
                    XYPlot xyPlot = chart.getXYPlot();
                    XYItemRenderer xyir = xyPlot.getRenderer();
                    xyir.setSeriesPaint(seriesIndex, color);
                } else {
                    System.out.println("setSeriesColor() unsupported plot: "+plot);
                }
            } catch (Exception e) { //e.g. invalid seriesIndex
                System.err.println("Error setting color '"+color+"' for series '"+seriesIndex+"' of chart '"+chart+"': "+e);
            }
        }//else: input unavailable
    }//setSeriesColor()

Instead of printing an eroor message the exception could be thrown - but i wanted an easy API where you don't need to enclose each method in try/catch just to ignore unsupported plots/renderers/axes.

As this class is a wrapper, each method has a JFreeChart object as a parameter. Another solution would have been to subclass JFreeChart which would be a "new" JFreeChart with this clean API.

Of course, i wished at the beginning of using JFreeChart that such an easy API already exists but i had to fight myself through all the internal stuff, not to mention the vertical/horizontal axis that were later replaced.
Wouldn't it be easier for new JFreeChart users to have an easier API?

Matthias · Post by **Matthias** » Thu Sep 04, 2003 12:44 pm

Seems you forgot the pan functionality. I cite you from message
http://www.jfree.org/phpBB2/viewtopic.p ... =pan#11611 :
"This isn't supported in JFreeChart at present, but it will be added before 1.0.0 is released."

There are several requests/proposals about it in this forum which you get searching for keyword "pan".

Post by **david.gilbert** » Fri Sep 05, 2003 12:21 am

mhilpert wrote:The result is a single class (which I call JFreeChartGenerator) that offers a clean API with methods like:

setAxisLabel(JFreeChart chart, int axisId, String label)
setMaximumAxisValue(JFreeChart chart, int axisId, double value)
setSeriesColor(JFreeChart chart, int seriesIndex, Color color)
setTickMarksVisible(JFreeChart chart, int axisId, boolean state)
...
and lots more.

It's a valid approach, and one which I considered right at the beginning when I started coding JFreeChart. But I chose not to do it (instead opting for the more specialised classes that you can mix-and-match) because, even though I would concede that it is easier to learn that kind of one-class-fits-all API, I personally think it becomes frustrating when you find a lot of methods that are available but don't apply (e.g. setAxisLabel for a pie chart).

I'm hopeful that now that the horizontal/vertical mess is gone (wish I'd thought that through a little better

) it is going to be easier for new users to understand the chart --> plot --> renderer structure.

There are tradeoffs between the two approaches and I wouldn't say one was overwhelmingly better than the other, but I'm still happy with the choice I made.

www.jfree.org

Roadmap...

Roadmap...

Thread synchronization

feature voting

Item Labels & Internationalization

What about Pan?