The IlvChartServletSupport class

Programmer's documentation > Building Web Applications > Developing JViews Charts JavaScript Web applications > The IlvChartServletSupport class

Describes the use of the IlvChartServletSupport class in handling HTTP requests to generate an image or an image map.

Overview

Introduces the IlcChartServletSupport class.

The image request

Describes the syntax and parameters of an image request.

The image map request

Describes the syntax and parameters of an image map request and the process for generating or customizing image maps..

Overview

The IlvChartServletSupport class responds to HTTP requests to generate an image from an IlvChart. This class allows you to add the functionalities of the JViews Charts Servlet framework into your existing servlets by invoking the handleRequest method from your servlet doGet method.

The servlet support can respond to two different types of HTTP requests:

image request

image map request

The image request

The image request produces either a JPEG or PNG image from the IlvChart. The syntax is:

myservlet?request=image

&width=width of the returned image

&height=height of the returned image

&format=output format of the returned image

[&bgcolor=image background color]

[&action=name of a server action]

[&comp=the chart component to dump]

The following table contains a detailed description of the parameters:

Parameter name	Parameter value	Description
request	image	Asks the servlet to generate an image.
width	Integer	Width of the image.
height	Integer	Height of the image.
format	“JPEG” “PNG”	Format of the resulting image.
comp	“chart” “area” “legend”	The component to dump.
bgcolor	An hexadecimal color value as “0xRRGGBB”	The background color of the image.
action	String	The action name to be executed on the servlet.

For example, the following request produces an image of size (300, 200) of an IlvChart component as a PNG image:

myservlet?request=image&width=300&height=200&comp=chart&format=PNG

The image map request

The image map request produces a client-side image map associated with an image. The image can be:

Explicitly specified in the request (as a URL),

Dynamically generated by the servlet. In this case, you should specify the parameters for the image request in addition to the image map request parameters.

The syntax of the image map request is:

myservlet?request=imagemap

&width=width of the image

&height=height of the image

[&mapname=imagemap]

{[&image=URL of an image] | {

[&format=output format of the image]

[&comp=chart]

[&bgcolor=image background color]

[&action=name of a server action]}}

The following table contains a detailed description of the parameters:

Parameter name	Parameter value	Description
request	“imagemap”	Ask the servlet to generate an image map.
width	Integer	Width of the image.
height	Integer	Height of the image.
mapname	String	The name of the map. The default value is “imagemap”.
image	String	The URL of an associated image. If this parameter is not specified, then an image is automatically generated.
format	“JPEG”, “PNG”	Format of the image automatically generated. This parameter is required only if no image parameter has been specified.
comp	“chart”, “area”, “legend”	The component to dump. This optional parameter is only taken into account if no image parameter has been specified. The default value is “chart”.
bgcolor	An hexadecimal color value as “0xRRGGBB”	The background color of the image.
action	String	The action name to be executed on the servlet.

For example, the following request asks for the servlet to generate both an image and an image map:

http://host/servlet/myservlet?request=imagemap

&width=400

&height=200

&format=JPEG

The resulting HTML code looks like:

...

</map>

<img usemap="#imagemap" width="400" height="330" src="/servlet/myservlet?request=image&height=330&width=400&format=JPEG"" border=0>

The call generates an HTML code fragment containing a client-side image map definition and an image. The contents of the image is then generated by another call to the servlet by means of an image request.

Generating an image map

Image maps are images with an attached map that points out certain hot spots, or clickable areas. In the JViews Charts library, a clickable area can be generated for specific data points or whole data sets.

The image map generation is handled by the IlvChartServletSupport class, and performed by means of an instance of the IlvImageMapBuilder class. This class is responsible for generating the area tags of the image map according to a specified configuration. The IlvImageMapBuilder instance used during the image map generation is retrieved with the createImageMapBuilder factory method.

Area tags are generated according to a configuration that is defined by an instance of a concrete implementation of the IlvIMapDefinition abstract class. A default implementation of this class is provided by means of the IlvDefaultIMapDefinition class.

The map definition instance is retrieved by invoking the getIMapDefinition method. By default, this method returns null leading to an empty image map area. You should override this method to return an IlvIMapDefinition instance configured with the correct attribute values of the area tags.

The IlvIMapDefinition abstract class also determines what the area tags represent: a whole data set or specific data points. This is called the map definition type, and is specified at construction time as a parameter to the IlvIMapDefinition constructor. This type can be retrieved using the getType method. A data points-based image map has the POINT_MAP type and a data set-based image map has the DATASET_MAP type.

By default, the generated attributes of the area tags are SHAPE, COORDS, HREF, TITLE and ALT.

Area tags attributes are handled through IlvIMapAttributes instances. This interface defines the necessary methods to fetch the HREF, TITLE, ALT, and TARGET attributes values, the SHAPE and COORDS attributes values being automatically generated. A default implementation is provided by means of the IlvDefaultIMapAttributes class. This class handles HREF and TITLE values separately (both can be null ), and maps the values of the ALT attribute to the values of the TITLE attribute.

The following example shows an IlvChartServletSupport subclass that overrides the getIMapDefinition method to return an IlvDefaultIMapDefinition instance configured with the POINT_MAP type and with specific HREF values for the HREF attributes:

protected IlvIMapDefinition getIMapDefinition(HttpServletRequest request,

IlvChart chart)

{

IlvIMapDefinition mapdef = null;

IlvDataSet dataSet = ...; // The data set for which we want map areas.

List hrefs = ...; // The list of href for the map area.

String[] hrefsValues = new String[hrefs.size()];

hrefsValues = (String[])hrefs.toArray(hrefsValues);

// Create attributes initialized with the contents of the hrefs list.

IlvIMapAttributes[] attrs = IlvDefaultIMapAttributes.create(hrefsValues);

try {

// Create a map definition that associates the data set with the

// area attributes.

mapdef =

new IlvDefaultIMapDefinition(new IlvDataSet[] {dataSet},

new IlvIMapAttributes[][] {attrs});

} catch (IllegalArgumentException e) {

System.err.println("Cannot create map definition :" + e.getMessage());

}

return mapdef;

}

Customizing image maps

The IlvChartServletSupport class allows you to customize the image generation by means of three methods:

createImageMapBuilder

This method allows you to return an instance of your own IlvImageMapBuilder subclass. This class is responsible for generating the image map HTML code fragment, that is:

The area tags corresponding to the renderers, by means of the getRendererTags method.

The area tag corresponding to the chart header, by means of the getHeaderTag method.

The area tag corresponding to the chart footer, by means of the getFooterTag method.

Each of these methods can be overridden if you need to perform additional actions.

getIMapDefinition

This method should be overridden to return an IlvIMapDefinition instance configured with area attributes.

generateMapAreaTags

This method is the core of the image map generation process. The default implementation first creates an IlvImageMapBuilder instance invoking createImageMapBuilder. Then, it generates the renderer area tags calling the IlvImageMapBuilder.getRendererTags method, passing the IlvIMapDefinition instance returned by getIMapDefinition as parameter.

NOTE 	The default implementation does not generate the header and footer tags. You have to override the generateMapAreaTags method and explicitly call IlvImageMapBuilder.getFooterTag and IlvImageMapBuilder.getHeaderTag methods.