ChartDirector 6.1 (Java Edition)

BaseChart.makeSession


Usage

public String makeSession(HttpServletRequest request, string name [, int imageFormat [, String filename [, boolean asAttachment ]]])

Description

Generates the chart as an image, saves it to a session variable and returns query parameters for loading the image.

The makeSession method is designed to support web applications in which the chart is generated in the script that outputs HTML.

This method requires session variables be enabled in the web server, which should be the default for JSP servers.

HTML cannot "contain" any image. It can only contain the URL of the images, typically in <IMG> tags. Other tags, such as <IFRAME>, <OBJECT> or <EMBED>, or the "background" property of CSS, etc, can also be used. The browser will use the URLs to load the images from separate HTTP connections.

In the followings, for conciseness, we will use <IMG> in the description. It should be noted that the description applies to other tags that can load chart images.

As HTML cannot contain any image, the script that outputs HTML cannot output the chart image. It needs to save the image in some place, and output an <IMG> tag with an URL for retrieving the saved image.

To save the chart image, a common method is to save it to the hard disk. The URL to load the image is then the URL of the image file. Please refer to BaseChart.makeTmpFile if you would like to consider this method.

The makeSession method saves images in session variables, avoiding creating image files on the hard disk. The makeSession method returns a URL query string, which can be used with a ChartDirector utility script "getchart.jsp" to load the image from session variables.

To avoid having to save the chart image at all, an alternative approach is to put the URL of a script in the <IMG>. The browser will then access the script to load the image. The script can generate the chart image and streamed directly to the browser. In this case, the chart is not generated by the script that outputs HTML, but by another script that handles the <IMG> tag.

A limitation of this method is that the charts cannot use image maps. Image maps are HTML tags (<MAP> and <AREA> tags) and can only be outputted by the script that generates HTML. If image maps are used, the charts need to be generated in the script that outputs HTML.

In a typical application, the chart is created like:

String chart1URL = c.makeSession(request, "chart1");

The web page then includes an <IMG> tag as follows:

<img src='<%=response.encodeURL("getchart.jsp?"+chart1URL)%>'>

Note that the above assumes "getchart.jsp" is in the same directory as your script. If it is in a different directory, you would need to modify the path in the <IMG> tag. Also, the directory that contains "getchart.jsp" must be in the same web application (servlet context) as your script, otherwise "getchart.jsp" will be unable to access the session variables created by your script.

As an alternative to "getchart.jsp", ChartDirector also has a GetSessionImage servlet that performs the same function. This is useful for servlet applications that do not use JSP.

For example, if you have mapped "*.chart" to GetSessionImage, you may use "getchart.chart" as the URL instead of "getchart.jsp". Please refer to the Installation section for details.

Note: The getimage.jsp may not work properly in some very old web servers. In this case, the getimage.jsp will automatically redirect itself to the GetSessionImage servlet. Therefore, it may be useful to install the GetSessionImage servlet even if you may not need it.

On the browser side, if the user attempts to save the image, such as by right clicking on the image and select "Save Image As" or something similar, the browser by default should derived a filename from the image URL. When makeSession is used, the URL is that of the script file "getchart.jsp". Using this as the filename of the image may not be desirable. In this case, the filename argument can be used to suggest an alternative filename to the browser.

When the image is sent to the browser, HTTP allows it to be marked as an attachment. In this case, if the receiving HTML element is an <IFRAME>, <FRAME> or the browser window itself, the browser should save it as a file instead of displaying it. Some browsers may prompt the user for the directory to use, while others may save it to a special "download directory" without prompting the user. The asAttachment argument can be used to mark the image as an attachment.

Arguments

ArgumentDefaultDescription
request(Mandatory)The HttpServletRequest object representing the current request.
name(Mandatory)The name of the session variable used to store the chart image. If there are multiple chart images in the same web page, each image must use a different name.
imageFormatPNGA constant representing the format of the image. Must be one of the predefined constants PNG, JPG, GIF, BMP, WMP, SVG, SVGZ or PDF.
filename""The suggested filename to use when user saves the chart image as a file on the browser side.
asAttachmentfalseSpecifies whether the image is intended as an attachment.

Return Value

A string representing the query parameters for retrieving the image using "getchart.jsp" or the GetSessionImage servlet.