JMSL Chart Guide: Web Server Application

JMSL Chart
Programmer's Guide

Web Server Application

Web Server Application

A JMSL chart can be returned as an image from a Web server using a servlet. The mechanism depends on the version of the Java runtime library being used.

With JDK 1.4 or later, images are rendered using the standard Java class javax.imageio.ImageIO. This class can be used on a headless server—that is, a server running without graphical interfaces. While most desktop Unix systems run the X Windows System, Unix servers are often run without it. Java runs in a headless mode if the system property java.awt.headless is set to true.

With JDK 1.3 or earlier, the ImageIO class cannot be used because it does not exist in older versions of Java. Instead the Java Advanced Imaging (JAI) Toolkit is used. JAI is not included with JMSL. It is a standard Java extension that can be downloaded, for free, from Sun's JAI download site. Also, it requires that a windowing system must be running. With Microsoft Windows this is not usually a problem. A headless server cannot be used; on Unix, X Windows, or its equivalent, must be running.

Overview—Web Servlets

Java Server Pages (JSP) and servlets are the standard mechanism for adding Java functionality to Web servers.

Adding charts to a Web page is complicated by the fact that in response to a request a Web server can return either a text HTML page or a bitmap image. The response to the initial request is an HTML page that contains an image tag. When the browser parses the HTML page and finds the image tag, it makes a second request to the Web server. The Web server then returns the bitmap image in response to this second request.

The JMSL classes JspBean and ChartServlet are used to coordinate this process. During the first request, one or more JMSL chart trees are constructed and stored in the HttpSession object, obtained from the HttpServletRequest object, using the method JspBean.registerChart. The method Jsp.getImageTag is used to construct an HTML image tag with an identifier for the chart in the session object. This image tag refers to the servlet ChartServlet. The second browser request is therefore directed to the ChartServlet, which uses the identifier to retrieve the chart from the session object. The Java Advanced Imaging library is used by the servlet to render the chart as a PNG image, which is returned to the browser.

The use of the session object to hold the chart requires that the user's browser allow cookies, used to track sessions across requests.

Generating a Chart with a JSP

This example consists of a JSP working with a bean (pieChart) that contains a JspBean. The HTML image tag is the value of the imageTag property from pieChart. The following is the JSP.

(Download Code)

 1  <%@page contentType="text/html"%>
 2  <jsp:useBean id="pieChart" scope="page" class="SampleChartBean"/>
 3  <html>
 4  <head><title>Pie Chart</title></head>
 5  <body>
 6  <h1>Pie Chart</h1>
 7  <jsp:setProperty name="pieChart"  property="*"/>
 8  <% pieChart.createChart(request); %>
 9  <jsp:getProperty name="pieChart"  property="imageTag"/>
10  </body>
11  </html>

In the above JSP, line 1 flags that an HTML page is being generated. Line 2 creates the object pieChart, which is an instance of SampleChartBean. This object has page scope, so it is discarded after the page has been generated. Line 7 sets attributes in pieChart using parameters in the request. Attributes are set in pieChart using its setter methods, following the usual pattern for Java beans. Line 8 calls the createChart method to create the chart tree and store it in the session. This is Java code enclosed in the special delimiters. Line 9 inserts the HTML image tag obtained by calling pieChart.getImageTag().

The class SampleChartBean uses a JspBean. It creates a pie chart and registers it with the session obtained from the request. The getImageTag() method returns an HTML tag which refers to the ChartServlet servlet that returns the chart image to the browser.

(Download Code)

import com.imsl.chart.*;
import java.awt.Color;

public class SampleChartBean {
    private JspBean bean;
    
    public SampleChartBean() {
        bean = new JspBean();
        bean.setSize(300, 300);
    }
    
    public void createChart(javax.servlet.http.HttpServletRequest request) {
        Chart chart = new Chart();
        bean.registerChart(chart, request);
        
        double y[] = {35., 20., 30., 40.};
        Pie pie = new Pie(chart, y);
        pie.setLabelType(pie.LABEL_TYPE_TITLE);
        pie.setFillOutlineColor(Color.blue);

        PieSlice[] slice = pie.getPieSlice();

        slice[0].setFillColor(Color.red);
        slice[0].setTitle("Red");
        
        slice[1].setFillColor(Color.blue);
        slice[1].setTitle("Blue");
        slice[1].setFillOutlineColor(Color.yellow);
        
        slice[2].setFillColor(Color.black);
        slice[2].setTitle("Black");
        slice[2].setExplode(0.3);
        
        slice[3].setFillColor(Color.yellow);
        slice[3].setTitle("Yellow");
    }
    
    public String getImageTag() {
        return bean.getImageTag();
    }
}

Generating Charts with Client-side Imagemaps

Client-side image maps allow regions of an image to be linked to a URL. Clicking on such a region behaves the same as clicking on a hypertext link. This can be used to create a degree of interactivity. Target regions are created for chart nodes that have the HREF attribute defined.

In this example the sample pie chart as above is generated, but now when the user clicks on a slice the selected slice is exploded out. Now pieChart is an instance of SampleImageBean. The JSP gets the pieChart's imageMap property to create a map tag in the HTML code.

(Download Code)

<%@page contentType="text/html"%>
<jsp:useBean id="pieChart" scope="page" class="SampleImagemapBean" />
<html>
<head><title>Pie Chart Imagemap</title></head>
<body>
<h1>Pie Chart Imagemap</h1>
<jsp:setProperty name="pieChart"  property="*"/>
<% pieChart.createChart(request); %>
<jsp:getProperty name="pieChart"  property="imageMap"/>
<jsp:getProperty name="pieChart"  property="imageTag"/>
</body>
</html>

The code for SampleImagemapBean is similar to the code for the previous SampleChartBean, but with the HREF attribute defined in each slice. The reference is back to SampleImagemapJSP, but with the explode parameter defined. The second change is the addition of a setter method for explode. The line

<jsp:setProperty name="pieChart" property="*"/>

in the JSP file sets properties in the pieChart from parameters in the request. If explode is defined in the HTTP request, then the JSP calls this setter method.

(Download Code)

import com.imsl.chart.*;
import java.awt.Color;

public class SampleImagemapBean extends JspBean {
    private JspBean bean;
    private int     explode;
    
    public SampleImagemapBean() {
        bean = new JspBean();
        bean.setSize(300,300);
        bean.setCreateImageMap(true);
    }
        
    public void createChart(javax.servlet.http.HttpServletRequest request) {
        Chart chart = new Chart();
        
        double y[] = {35., 20., 30., 40.};
        Pie pie = new Pie(chart, y);
        pie.setLabelType(pie.LABEL_TYPE_TITLE);
        pie.setFillOutlineColor(Color.blue);

        PieSlice slice[] = pie.getPieSlice();

        slice[0].setFillColor(Color.red);
        slice[0].setTitle("Red");
        
        slice[1].setFillColor(Color.blue);
        slice[1].setTitle("Blue");
        slice[1].setFillOutlineColor(Color.yellow);
        
        slice[2].setFillColor(Color.black);
        slice[2].setTitle("Black");
        
        slice[3].setFillColor(Color.yellow);
        slice[3].setTitle("Yellow");
        
        for (int k = 0;  k < slice.length;  k++) {
            slice[k].setHREF("SampleImagemapJSP.jsp?explode="+k);
        }
        
        try {
            slice[explode].setExplode(0.3);
        } catch (Exception e) {
            // ignore out of range values for explode
        }
        
        bean.registerChart(chart, request);
    }
    
    
    
    public void setExplode(int explode) {
        this.explode = explode;
    }
    
    public String getImageTag() {
        return bean.getImageTag();
    }
    
    public String getImageMap() {
        return bean.getImageMap();
    }
}

Servlet Deployment

A Web server that supports Java servlets will generally have a directory of Web applications, one per directory. In each Web application subdirectory there can be a WEB-INF directory containing the Java classes. This directory contains the subdirectory classes, containing individual class files, and the subdirectory lib, containing JAR files. For the above example, the file structure would be as follows:

webapps/
    application_name/
        SampleChartJSP.jsp
        SampleImagemapJSP.jsp
        WEB-INF/
            web.xml
            classes/
                SampleChartBean.class
                SampleImagemapBean.class
            lib/
                jmsl.jar
                jai_core.jar
                jai_codec.jar

The file jmsl.jar contains the JMSL classes. The files jai_core.jar and jai_codec.jar contain the JAI classes.