RCHART, User Guide

Copyright 2007, J4L Components (http://www.java4less.com)
Go bak to contents

JSP and Servlet

• Running as servlet
• Running in JSP pages
• Using the RChart JSP Tag library
• Interactive web charts
• Realtime web charts
  
• Unix and Linux servers

While applets are small Java programs that run in the browser (client), servlets and JSP pages are server side programs which run in the web server and the output in GIF, PNG or JPEG format is sent to the browser. RChart can run as servlet or inside JSP pages. The product includes ready to use examples for both cases.

Running as servlet

The servlet class is called com.java4less.rchart.web.ChartServlet. Basically you just need to call the servlet and send the chart's parameters either using the GET or the POST method. However the recommended way is using the DATAFILE parameter to tell the servlet where it can get the parameters from (either from a file or a url).

In all cases the servlet supports 3 additional parameters:

• WIDTH: width in pixels of the output image. (default is 500).
• HEIGHT: height in pixels of the output image. (default is 500).
• FORMAT: format of output image, "gif", "png" or "jpeg". (default is JPEG).
  use the parameter DATAFILE if you want to read the chart definition from a file.
  Note: RChartServlet requires jdk 1.2 or newer. It is however possible to make a jdk 1.1 compatible version.
  
  If you want to create a PNG or GIF image you will need to download the encoder:

• PNG (by Walter Brameld , wbrameld4@yahoo.com): download it from http://209.51.137.74/pngencoder-1.0.jar
• GIF: download gif encoder from http://www.acme.com/resources/classes/Acme.tar.gz

Example, Tomcat 5:

In order to run the servlet using Tomcat 5 you can follow these steps:

1. create a new empty directory for rchart in Tomcat: "tomcatdirectory\webapps\rchart2"
2. copy the file "examples_servlet\web.xml" to "tomcatdirectory\webapps\rchart2\WEB-INF\web.xml"
3. copy the areaCurves.txt file from the "data\examples" directory to "tomcatdirectory\webapps\rchart2".
4. Copy the image files from the "data" directory to "tomcatdirectory\webapps\rchart2\WEB-INF\classes". This is only required if you want to view one of charts that uses a background image.
5. copy bin\rchart2.jar to "tomcatdirectory\webapps\rchart2\WEB-INF\lib"
6. start Tomcat
7. Open the following URL in you browser:
   
   http://localhost:8080/rchart2/servlet/RChartServlet?DATAFILE=http://localhost:8080/rchart2/areaCurves.txt
   
   Note 1: if you want to use the PNG or the GIF encoder you must copy the jar file to "tomcatdirectory\webapps\rchart2\WEB-INF\lib"

If you have any problems running the servlet check the following:

• The servlet is actually being executed, look in the java console or in the servlets logs if there are messages written by the servlet.
• The data file can be found. Enter "http://localhost:8080/rchart2/areaCurves.txt" in your browser to check if it can be found.

Running in JSP pages

JSP pages are more flexible than the ChartServlet but you need to deal with a bit of Java/JSP programming. RChart however includes a small JSP application which can be used with none or little modification.

A simple JSP page to display a chart is:

<%
String encode="jpeg";
String myurl="http://localhost:8080/rchart2/";
String dataFile="combined2Positions.txt";

// set response headers
response.setContentType("image/"+encode);
response.setDateHeader ("Expires",0);

// get output stream
java.io.OutputStream outb=response.getOutputStream();

// create Chart from data file
com.java4less.rchart.ChartLoader loader=new com.java4less.rchart.ChartLoader();
loader.loadFromFile(myurl+dataFile,false);
com.java4less.rchart.Chart chart=loader.build(false,false);

// set size of the chart
chart.setSize(500,500);

// encode image and send output to the browser
chart.saveToFile(outb,encode);
outb.close();
%>

Example, Tomcat 5:

In order to run the JSP examples using Tomcat 5 you can follow these steps:

1. create a new empty directory for rchart in tomcat: "tomcatdirectory\webapps\rchart2"
2. copy all files from the "data\examples" directory to "tomcatdirectory\webapps\rchart2".
3. Copy all image files from the "data" directory to "tomcatdirectory\webapps\rchart2\WEB-INF\classes".
4. copy bin\rchart2.jar to "tomcatdirectory\webapps\rchart2\WEB-INF\lib"
5. start Tomcat
6. Open the following URL in you browser:
   
   http://localhost:8080/rchart2/Examples.htm
   
   Note 1: if you want to use the PNG or the GIF encoder you must copy the jar file to "tomcatdirectory\webapps\rchart2\WEB-INF\lib"and change the following line in all JSP pages:
   
   String encode="jpeg";

Note: You can also use RChart JSP Tag library to create charts without any java code.

Interactive web charts

RChart can create image maps for the chart images which provides you with the following features:

1. Tooltips are shown when the mouse is placed over a bar or point.
2. HTML links: a new html link can be openned when the user click's on a point in the chart.
3. Actions: for example javascript functions can be executed when the user click's on a point in the chart.

The following parameters are used for defining tips and links:

• CHART_SHOW_TIPS. Set it to "true" in order to activate tips.
• SERIE_TIPS_*: list of tips for the values of the serie. For example, if serie 1 has 3 bars:
  
  SERIE_TIPS_1=tip for first bar|tip for second bar| tip for third bar
  
  
• SERE_POINT_1=true. Linecharts require the points to be active.
• SERIE_LINKS_*: list of html links, for example :
  
  http://www.server.com/value1.html|http://www.server.com/value2.html|http://www.server.com/value3.html
  
  you can also execute javascript functions, for example:
  
  javascript:alert('hello world')
  
  
• CHART_LINKS_TARGET: this is the frame or window where the html links should be openned (the default value is _new)

In order to create a chart and its associate image map you need 2 servlets or 2 JSP pages. One of them is in charge of creating the chart's image and the other is in charge of creating the image map.

You can use the html links to open a subchart when the user clicks on a given point of the chart, in this way you are creating drill-down charts.

JSP pages

The following code creates a chart and the image map. Note that the page itself only creates the HTML image map and a IMG tag which calls a second JSP script that will deliver the JPEG image (see "examples_jsp" directory).

 

<%
String encode="jpeg";
String myurl="http://localhost:8080/rchart2/";
String dataFile="combined2Positions.txt";

response.setContentType("text/html");
response.setDateHeader ("Expires",0);

// get output stream
java.io.PrintWriter outb=response.getWriter();

// create Chart from data file
com.java4less.rchart.ChartLoader loader=new com.java4less.rchart.ChartLoader();
loader.loadFromFile(myurl+dataFile,false);
com.java4less.rchart.Chart chart=loader.build(false,false);

// set size of the chart
chart.setSize(w,h);

// we must paint the chart once before we can retrieve the image map
com.java4less.rchart.gc.ChartImage chartImage= com.java4less.rchart.gc.GraphicsProvider.createImage(w,h);
com.java4less.rchart.gc.ChartGraphics chartGraphics=chartImage.getGraphics();
chart.paint(chartGraphics);
chartGraphics.dispose();
chartImage.dispose();

// retrieve image map
String htmlMap=chart.getHTMLImageMap("Chart");

// html output
outb.print("<html>");
outb.print("<body>");
// IMG tag which includes the link to the second JSP page
outb.print("<img src='getChart.jsp?chart="+dataFile+"' BORDER=0 NAME='ICHART' USEMAP='#Chart'>");
// output image map now
outb.print(htmlMap);
outb.print("</body>");
outb.print("</html>");

outb.close();
%>

Servlet

RChart only includes a servlet which can create image maps. The name of the servlet is com.java4less.rchart.web.ChartMapServlet and must be used in the same way as the ChartServlet. Note that he ChartMapServlet creates the image map only, not the image itself.

Realtime web charts

In some applications you need the chart to be continuosly be updated with new data. The following two files in the "examples_jsp" directory shows you how to do it:

• getDynamicChart.jsp: this file creates a new chart each time it is called. It creates a chart with new data based on the time in your computer, so the data will keep on changing.
• getRealtimeChart.jsp: this is the main file. It includes a link to the getDynamicChart.jsp and a small javascript program that will regularly refresh the image.
  

   

Note that the browser must be Javascript enabled to support this feature. The Javascript function for refreshing the chart is very simple:

function refreshChart(){

document.ICHART.src='getDynamicChart.jsp';

setTimeout("refreshChart()",3000);

}

the function calls itself every 5 seconds and reload the image called ICHART. The image is defined as:

<img src='getDynamicChart.jsp' BORDER=0 NAME='ICHART'>

Unix and Linux servers

If you run RChart on a Unix or Linux server you must take into account the following. Java graphics classes require a X11 server to be running. This is a well known java problem.

If you are not running a X11 server you will get errors like:

Exception java.lang.NoClassDefFoundError
at java.lang.Class.forName0(Native Method) at java.lang.Class.forName(Class.java:120)
at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment (GraphicsEnvironment.java:58)
....

or

java.lang.InternalError: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable. at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method)
.

or similar.

The most common solutions to this problem are:

• If you run Java 1.4 or later you can use java in headless mode. This is done by starting the java machine with the "-Djava.awt.headless=true" parameter.
• If you run Java 1.1, 1.2 or 1.3 you can install a dummy X server, such as the Xvfb utility.