<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>jfreechart</name>
  <title>JFreeChart Sample</title>
  <description>Shows how third-party charting APIs could be used for rendering charts as images.</description>

  <mainFeature ref="jfreechart"/>
  
  <!-- jfreechart -->
  
  <feature name="jfreechart" title="Rendering Images Using Third Party APIs (JFreeChart Library)">
    <description>
How to render images using the <a href="http://jfree.org/jfreechart/">JFreeChart</a> library.
    </description>
    <since>0.6.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="xchart"/>
    <content>
<b>Rendering Graphic Objects</b>
<br/>
<br/>
Usually, the mechanism of producing complex images, charts and other graphic objects is part of some more specialized Java libraries, 
and does not represent one of the JasperReports goals. However, one of its important goals is to easily integrate within a 
generated report charts, barcodes and other graphics produced by third party libraries.
<br/>
This integration is based on the fact that great majority of graphic objects produced by these libraries can output 
to image files or in-memory Java image objects. Then all these generated image objects can be handled by the JasperReports engine 
using a normal image element, as described in the <a href="../images/index.html#images">Images</a> sample. 
<br/>
One problem is that the content of an image element can come either directly from an image file like a JPG, 
GIF, PNG, or can be a Scalable Vector Graphics (SVG) file that is rendered using some 
business logic or a dedicated graphics API related to a specific charting or a barcode library. In this case,
JasperReports treats all kind of images in a very transparent way because it relies on a special 
interface called <api href="net/sf/jasperreports/engine/JRRenderable.html">JRRenderable</api> to offer a common way to render images.
<br/>
The <code>JRRenderable</code> interface has a method called 
<code>render(Graphics2D grx, Rectangle2D r)</code>, which gets called by the engine each time it needs to draw the image 
on a given device or graphic context. This approach provides the best quality for the 
SVG images when they must be drawn on unknown devices or zoomed into without 
losing sharpness. 
<br/>
Other methods specified in this interface can be used to obtain the native size of the 
actual image that the renderer wraps or the binary data for an image that must be stored 
in a separate file during export.
<br/>
The JasperReports library comes with a default implementation for the <code>JRRenderable</code> interface that 
wraps images that come from files or binary image data in JPG, GIF, or PNG format. 
The <api href="net/sf/jasperreports/engine/JRImageRenderer.html">JRImageRenderer</api> class is actually a container 
for this binary image data, which it uses to load a <code>java.awt.Image</code> object from it, 
which it then draws on the supplied <code>java.awt.Graphics2D</code> context when the engine 
requires it. 
<br/>
Image renderers are serializable because inside the generated document for each image is 
a renderer object kept as reference, which is serialized along with the whole <code>JasperPrint</code> object. 
<br/>
When a <code>JRImageRenderer</code> instance is serialized, so is the binary image data it contains. 
However, if the image element must be lazy loaded (see the <code>isLazy</code> attribute in the 
<a href="../images/index.html#images">Images</a> sample), then the 
engine will not load the binary image data at report-filling time. Rather, it stores inside 
the renderer only the <code>java.lang.String</code> location of the image. The actual image data 
is loaded only when needed for rendering at report-export or view time. 
<br/>
To simplify the implementation of SVG image renderers, JasperReports ships with an 
abstract renderer: <api href="net/sf/jasperreports/engine/JRAbstractSvgRenderer.html">JRAbstractSvgRenderer</api>. This 
implementation contains the code to produce binary image data from the SVG graphic in 
JPG format. This is needed when the image must be stored in separate files on disk or 
delivered in binary format to a consumer (like a web browser). 
<br/>
Specific image renderers are called when the class of the <code>&lt;imageExpression/&gt;</code> element 
is <code>net.sf.jasperreports.engine.JRRenderable</code>. In this case the image expression value should point 
to a <code>JRRenderable</code> object which is designated to render the image.
<br/>
<br/>
<b>Rendering a JFreeChart Object Example</b>
<br/>
<br/>
This sample shows how to integrate a <code>JFreeChart</code> pie chart into a report, 
letting the JFreeChart engine to draw itself the chart.
<br/>
In order to put together both the <code>JFreeChart</code> chart and the <code>JRRenderable</code> renderer, the 
<code>JFreeChartReport.jrxml</code> template provides a scriptlet class atribute: <code>scriptletClass="JFreeChartScriptlet"</code>.
The scriptlet class source is available as <code>JFreeChartScriptlet.java</code> file in the <code>src</code> directory. 
<br/>
In the <code>afterReportInit()</code> method, a chart object is created, with all necessary information to be represented:
<pre><![CDATA[
  DefaultPieDataset dataset = new DefaultPieDataset();
  dataset.setValue("Java", 43.2d);
  dataset.setValue("Visual Basic", 10.0d);
  dataset.setValue("C/C++", 17.5d);
  dataset.setValue("PHP", 32.5d);
  dataset.setValue("Perl", 1.0d);
	
  JFreeChart chart = 
    ChartFactory.createPieChart3D(
      "Pie Chart 3D Demo 1",
      dataset,
      true,
      true,
      false
      );
	
  PiePlot3D plot = (PiePlot3D) chart.getPlot();
  plot.setStartAngle(290);
  plot.setDirection(Rotation.CLOCKWISE);
  plot.setForegroundAlpha(0.5f);
  plot.setNoDataMessage("No data to display");
]]></pre>
The resulting chart is passed to a <api href="net/sf/jasperreports/renderers/JCommonDrawableRenderer.html">JCommonDrawableRenderer</api> 
class constructor. The <code>JCommonDrawableRenderer</code> extends the <code>JRAbstractSvgRenderer</code> class nominated above, and its 
constructor needs an <code>org.jfree.ui.Drawable</code> object, characterized by its <code>draw()</code> method. A <code>JFreeChart</code> chart 
represents such a <code>Drawable</code> object.
<br/>
The <code>render()</code> method in the <code>JCommonDrawableRenderer</code> class just calls the <code>Drawable</code> object's <code>draw()</code> method, 
and all the rendering stuff will be done by this dedicated API:
<pre><![CDATA[
  public JCommonDrawableRenderer(Drawable drawable) 
  {
    this.drawable = drawable;
  }

  public void render(Graphics2D grx, Rectangle2D rectangle) 
  {
    if (drawable != null) 
    {
      drawable.draw(grx, rectangle);
    }
  }
]]></pre>
Once the renderer gets available, one have to instruct the JasperReports engine to use it. The new renderer is passed to the engine in the <code>Chart</code> report variable:
<pre><![CDATA[
  this.setVariableValue("Chart", new JCommonDrawableRenderer(chart));
]]></pre>
This variable is referred to in the <code>reports/JFreeChartReport.jrxml</code> file:
<br/>
<br/>
&#160;&#160;<code>&lt;variable name="Chart" class="net.sf.jasperreports.engine.JRRenderable" calculation="System"&gt;</code>
<br/>
<br/>
Now, let's take a look at the &lt;image/&gt; element itself:
<br/>
<br/>
<code>
&#160;&#160;&lt;image scaleImage="Clip" hAlign="Center" hyperlinkType="Reference"&gt;
<br/>
&#160;&#160;&#160;&#160;&lt;reportElement x="0" y="110" width="515" height="300"/&gt;
<br/>
&#160;&#160;&#160;&#160;&lt;graphicElement/&gt;
<br/>
&#160;&#160;&#160;&#160;&lt;imageExpression class="net.sf.jasperreports.engine.JRRenderable"&gt;&lt;![CDATA[$V{Chart}]]&gt;&lt;/imageExpression&gt;
<br/>
&#160;&#160;&#160;&#160;&lt;hyperlinkReferenceExpression&gt;&lt;![CDATA["http://www.jfree.org/jfreechart"]]&gt;&lt;/hyperlinkReferenceExpression&gt;
<br/>
&#160;&#160;&lt;/image&gt;
</code>
<br/>
<br/>
The image expression class is <code>net.sf.jasperreports.engine.JRRenderable</code>, and its value points to the <code>Chart</code> report variable 
prepared in the report scriptlet.
<br/>
<br/>
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/jfreechart</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/jfreechart/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.

    </content>
  </feature>

</sample>
