For a quick overview, see the
Chart Tag Tutorial page.
KavaChart's Custom Tag Library consists of a small set of easy to use tags
that hide the complexity of applying data and style information to
server-generated charts. These tags will help you effectively create persistent
data stores and style information to make chart image generation as efficient
as possible.
In addition, JSPs that contain these chart tags will be more intuitive and
easier to work with than extensive scriplet or servlet references for non-programmers
and programmers alike. These tags will make your pages more portable and flexible
and will promote re-use of your existing data sources.
This library is comprised of 3 chart generation tags and a few utility tags,
described below.
Start by adding this line to your JSP:
This assumes that your web.xml file has been configured with the same URI, and
that the web.xml file also references the kavachart-taglib.tld taglib
descriptor.
Usage:
This chart tag generates an encoded chart image and writes it to your server's
filesystem. It returns a reference to that image, along with (optionally)
an image map used to create tooltip labels.
All this tag's attributes are available for runtime expressions. The tag also
has a number of useful inner tags described later in this document.
Usage:
This chart tag generates an encoded chart image and saves it to your application
memory. The generated page includes an "IMG" tag that points to a
servlet used to retrieve the image and delete it from memory. This tag will
also (optionally) create an image map used to create tooltip labels to accompany
that image.
All this tag's attributes are available for runtime expressions. The tag also
has a number of useful inner tags described later in this document.
Usage:
This chart tag can be used for load balancing between multiple servers. By default this tag will encode any chart options and pass them to com.ve.kavachart.servlet.LoadBalancedChartServlet where the actual chart is created. This is useful in a mirrored resource environment as you can send a request for LoadBalancedChartServlet to any of the mirrored servers for chart generation and image encoding (at the very least the mirrored servers must have access to any property files or image files used in the encoding process). There is also the additional option of specifying a dedicated server to handle all chart creation. The generated page includes an "IMG" tag that points to LoadBalancedChartServlet using the default servletContext or optionally a user-specified context (for specifying a particular server). This tag will
also (optionally) create an image map used to create tooltip labels to accompany
that image.
All this tag's attributes are available for runtime expressions. The tag also
has a number of useful inner tags described later in this document.
Usage:
This chart tag generates an applet definition consistent with the server-side
imaging processes. This definition includes data defined by your DataProvider
classes, localization from ResourceBundles, and any other modifications
performed by the other Chart tags.
While your HTML coders may be familiar with applet definitions, this tag
provides you with the opportunity to separate style logic (properties stylesheets)
from your data in a simple tag. Chart data and properties are automatically
populated without cluttering the logic of your JSP source code.
Usage:
This tag generates an HTML table using chart styles and data sources. This tag allows you
to re-use a chart DataProvider class, chart localization information, and chart property
information in a concise, easyto-use tag.
HTML table styles are defined using CSS stylesheet classes defined in a conventional manner,
and data, formatting, and labelling information is derived from chart properties.
dataProviderID:
A string value that identifies this chart's DataProvider attribute. A
DataProvider class implements the KavaChart interface com.ve.kavachart.utility.DataProvider,
which supplies an Enumeration of com.ve.kavachart.chart.Dataset classes.
This class is placed into your page, session, or application context as a
named attribute. The dataProviderID identifies the name used to store
that DataProvider class.
A DataProvider is typically implemented as a part of your overall data retrieval
process, and can be placed into your page context at any point in the page
construction code. A DataProvider can also be a JavaBean.
Code Example:
Tag Example:
style:
A string value that defines this chart's property sheet. A property sheet is
a file that contains lines in form property=value. These files
can be generated easily with the
KavaChart ChartWizard. Because a property file is a simple ASCII file, you
can also edit it with a text editor, using the standard KavaChart server
bean property strings.
Example:
reloadStyle:
"true" or "false". By default, the chart's property sheet is loaded into
application memory for efficient re-use. If you want changes to the
property sheet to take effect without restarting your server, set "reloadStyle" to "true".
Example:
chartType:
A string value that describes the KavaChart server chart bean you want to use.
For example, if you specify "lineApp", the tag will use com.ve.kavachart.servlet.lineApp
to create the chart. ChartBean classes that aren't part of the com.ve.kavachart.servlet
package must use a fully qualified name, such as "kcfinance.ChartBean".
Example:
useLinkMap:
"true" or "false". By default, this attribute is "true" and the tag creates a
link map with "ALT" text to describe each point. While this is a nice feature
for simple charts, you may want to disable it for charts with a large number of
points.
Example:
resourceBundleID:
An attribute ID for this tag's resource bundle.
Resource bundles are typically used to localize chart attributes.
This attributes lets you define a resource
bundle at any point in the page generation process and use it to redefine
a chart's labels, titles, etc. You can even redefine the chart's style based on
resource bundle information.
Example:
resourceBundleBaseName:
A basename for a resource bundle used by this chart. If you don't use a common
resource bundle for all your page's attributes, you can still localize the chart
automatically using resource bundles.
Typically a resource bundle is a set of properties files consisting of property=value
statements. This file must be located within your application's CLASSPATH, and
must be named with a resourceBundleBaseName.properties. Localized
resource bundles use the convention resourceBundleBaseName_en.properties,
where "en" is replaced by the specific locale ID represented by that bundle.
Non-western strings are generally more efficient if placed into
ResourceBundle classes.
Resource bundle properties files are loaded and unloaded by the ClassLoader, so
they are cached efficiently in a platform-dependent way. You may need to restart
your server to see changes to your resource bundles take effect.
If your target languages includes non-Western languages, you may need to create
ResourceBundle classes to get the correct character information. Some languages require
specific character sets. In this case, you must also make sure your resource bundle specifies
the correct fonts for the characters you're using.
Example:
cacheDirectory:
(cached chart tag only)
Because the cached chart tag must write an image file to your server's filesystem,
it's important to specify where on the filesystem you wish to save the image.
The location specified here is relative to your application context, and
defaults to /images/KavaChartImages.
Since the tag will return an <IMG> reference to this file, files in the
cacheDirectory must be visible from a web browser.
Example:
codebase:
(applet chart tag only)
Applets use a CODEBASE attribute to determine security policies and class
file locations. This optional attribute defaults to your application's root directory.
You can set this value to point to another directory, or even another server
(which would contain your applet's jar file, image resources, etc.). Since
the chart's data is embedded into the parameters, you can easily host the applet
from another server.
Example:
archive:
(applet chart tag only)
Applets use an ARCHIVE attribute to point to a jar archive containing the applet's
code resources. This attribute defaults to KavaChart's applet naming
convention (e.g. com.ve.kavachart.applet.lineApp is contained in a jar archive named
applet.lineApp.jar), but you can override this in the case you have a customized applet.
Example:
streamServletName:
(streamed chart tag only)
By default the streamed chart tag points to a servlet named
/servlet/com.ve.kavachart.servlet.ChartStream to retrieve its image bytes. You may wish
to obscure this by changing the servlet-mapping attribute in your web.xml file,
and by applying this attribute to your streamed chart tag.
Example:
imageType:
(balanced chart tag only)
This attribute functions like the imageType server-side property and is a
required attribute for the balanced tag.
Example:
width:
(balanced chart tag only)
This attribute functions like the width server-side property.
Example:
height:
(balanced chart tag only)
This attribute functions like the height server-side property.
Example:
servletContext:
(balanced chart tag only)
Use this attribute to specify a specific servlet context path for load balancing.
The actual request to generate the chart will be sent to this path.
By defining this tag,
you can either send your chart requests to a mirrored cluster of servers, or to a
server that has been optimized for chart generation.
Example:
Usage:
An inner tag that reads data from a web service providing data conforming to the DTD
located at http://www.ve.com/kavachart/KavaChartDataProvider.dtd. A data sample is
located at http://www.kavachart.com/dat.xml.
serviceURL:
A web service URL containing the data you want to chart.
Example:
Usage:
This inner tag constrains the data provided by a referenced DataProvider
class. All attributes are settable by runtime expressions, and all attributes
are optional.
dataProviderID:
This is original DataProvider class to be filtered. Set this attribute at any
point in your page generation process, and the datafilter tag will limit
the emitted data to the attributes below.
startObservation:
This is the index (0 based) for the first point from the chart's DataProvider to appear
on the chart.
endObservation:
This is the index for the last point from the chart's DataProvider to appear
on the chart.
startDataset:
This is the index for the first Dataset from the chart's DataProvider to appear
on the chart.
endDataset:
This is the index for the last Dataset from the chart's DataProvider to appear
on the chart.
Example:
Usage:
This inner tag manipulates the data provided by a referenced DataProvider
class, scaling each value by a multiplier, and then adding to each value
as specified. All attributes are settable by runtime expressions, and all attributes
are optional.
dataProviderID:
This is original DataProvider class to be filtered.
multiplier:
This floating point value is used to scale each observation's Y values (e.g. Y, Y2, Y3, or
high/low/open/close). Default multiplier = 1.
adder:
This floating point value is added to the result of each multiplication. Default adder = 0;
Example:
Usage:
This inner tag changes row-wise observations into column-wise observations, or vice-versa.
It's typically used to regroup bars differently. For example, a default bar (column) chart
with multiple datasets creates clusters of bars; the first cluster is each dataset's first
observation, the second cluster is each dataset's second observation, and so on.
The datatransposer tag would alter that data so that the first cluster consists of all the first
dataset's observations, the second cluster consists of the second dataset's observations, and so on.
dataProviderID:
This is original DataProvider class to be filtered.
Example:
Usage:
An inner tag to combine several data sources into a single chart. This tag is particularly
useful when a page needs to display data in a variety of charts. For example, a page may
use one data source for each of two pie charts, and then combine the data sources into a single
bar chart.
dataProviderID:
A comma-delimited list of DataProviders to be combined.
Example:
Altenate Example:
Usage:
An inner tag to generate histogram metadata from incoming data sources. Data is automatically
arranged into a reasonable number of "bins", with ranges used to label the bins. This tag
is typically used with a column or bar chart.
dataProviderID:
A DataProvider to be analyzed.
binSize:
The number of items to be allocated to each histogram bin.
labelPrecision:
A decimal precision to be used for labelling each bin.
Example:
Usage:
An inner tag to generate metadata that describes the percentage change of incoming data source
Y values. This type of chart is typically used with time-series data to understand how
values have changed over time. It is common in financial services to use this technique
to compare two stocks, for example.
dataProviderID:
Incoming data to be analyzed.
Example:
Usage:
Linear regression is typically used to understand correlation between two variables. In practice,
these variables often exist as the dependent (Y) values of two different datasets. This tag uses Y
values from two datasets to create X and Y metadata for an output dataset. The output data is then
directed to a regressionApp chart or scatter plot to visualize the correlation between these variables.
dataProviderID:
Incoming data to be combined.
Example:
Usage:
A tag to sort incoming data sources. Combined with a column chart, this can turn data into a Pareto
analysis chart. You can also use this chart to visually understand other aspects of incoming data sources.
dataProviderID:
Incoming data to be sorted.
sortBy:
X|Y|Y2|Y3|label. Defaults to "Y".
Example:
Usage:
This inner tag provides datasets with random numbers to permit your
page designers to proceed with page development in the absence of a working
DataProvider class.
numDatasets:
(required) positive integer describing the number of datasets provided to this chart.
numObservations:
(required) positive integer describing the number of points
in each dataset provided to this chart. In essence, this tag installs itself
as the chart tag's DataProvider, regardless of what other attributes may be set.
Example:
Usage:
This inner tag provides datasets with random numbers to permit your
page designers to proceed with page development in the absence of a working
DataProvider class.
The X values in this DataProvider are timestamps, starting with now, and increasing
by a specified number of days for each observation. The default is one day
per point.
This simulator provides extended data suitable for charts that use CandlestickDatum,
such as candelstick charts, hi-lo-open charts, and so on.
numDatasets:
(required) positive integer describing the number of datasets provided to this chart.
numObservations:
(required) positive integer describing the number of points
in each dataset provided to this chart. In essence, this tag installs itself
as the chart tag's DataProvider, regardless of what other attributes may be set.
dayIncrement:
(required) positive integer describing the number of days between each point
in this DataProvider's datasets.
Example:
Usage:
This inner tag overrides properties set in the style properties file and
localized resource bundles. It provides a behavior similar to conventional
applet param tags, but can be set with JSP runtime expressions. This inner
tag can be set multiple times.
name:
(required) Name of property to override.
value:
(required) The property's new value.
Example:
Usage:
This inner tag overrides locale settings from your page or application
context. It's useful for testing resource bundles in an ad-hoc way.
localeString:
(required) Named locale, using the convention of country_variant
Example:
Implement this interface in any class to create a chart DataProvider.
A DataProvider is a class that supplies a chart tag
with an Enumeration of Dataset classes. A new instance of this class should
be created when your Datasets change to avoid thread contention issues. Generally
this means a new DataProvider for each page, although DataProviders that don't
change values very often (as in some of the weather examples) may be safely re-used.
Consult the com.ve.kavachart.chart.Dataset documentation for more information
on constructing Dataset classes. Convenient constructor signatures are available
for most situations.
To add KavaChart's Tag Library to your own application:
Consult the com.ve.kavachart.chart.Dataset documentation for more information
on constructing Dataset classes. Convenient constructor signatures are available
for most situations.
Include Statement
<%@ taglib uri="http://www.ve.com/kavachart-taglib" prefix="chart" %>
Cached Chart Tag
<chart:cached attr1="value1" attr2="value2" .../>
Streamed Chart Tag
<chart:streamed attr1="value1" attr2="value2" .../>
Balanced Chart Tag
<chart:balanced attr1="value1" attr2="value2" .../>
Applet Chart Tag
<chart:applet attr1="value1" attr2="value2" .../>
Table Tag
<chart:table attr1="value1" attr2="value2" .../>
Chart Tag Attributes
DataProvider myData = new MyDataSource();
pageContext.setAttribute("dataID", myData);
<chart:sreamed dataProviderID="dataID" />
<chart:streamed style="WEB-INF/myChart.properties" />
<chart:cached style="WEB-INF/myChart.properties" reloadStyle="true" />
<chart:cached chartType="pieApp" />
<chart:cached chartType="dateLineApp" dataProviderID="myData" useLinkMap="false" />
<chart:streamed chartType="pieApp" resourceBundleID="myResources" />
<chart:cached chartType="pieApp" resourceBundleBaseName="chartResources" />
<chart:cached chartType="pieApp" cacheDirectory="/images/charts" />
<chart:applet chartType="columnApp" codebase="/jarfiles/charts" />
<chart:applet chartType="custom.FancyChart" archive="FancyChart.jar" />
<chart:streamed streamServletName="charts" />
<chart:balanced imageType="swf" />
<chart:balanced width="400" />
<chart:balanced height="300" />
<chart:balanced servletContext="http://localhost:9019/" />
Data Web Service Inner Tag
<chart:datawebservice serviceURL="http://www.kavachart.com/dat.xml" .../>
<chart:streamed chartType="columnApp" >
<chart:datawebservice serviceURL="http://www.kavachart.com/weather.jsp" />
</chart:streamed>
Data Filter Inner Tag
<chart:datafilter startDataset="0" endDataset="7" .../>
<chart:streamed chartType="columnApp" >
<chart:datafilter dataProviderID="moneyChartData"
startObservation="20"
endObservation="120"
startDataset="2"
endDataset="2" />
</chart:streamed>
Data Arithmetic Inner Tag
<chart:dataarithmetic multiplier="0.001" ...>
<chart:streamed chartType="columnApp" >
<chart:dataarithmetic dataProviderID="smogLevels"
adder="50"
multiplier="100" />
</chart:streamed>
Data Transposer Inner Tag
<chart:datatransposer .../>
<chart:streamed chartType="columnApp" >
<chart:datatransposer dataProviderID="salesData" />
</chart:streamed>
Data Accumulator Inner Tag
<chart:dataaccumulator dataProviderID="source1,source2".../>
<chart:streamed chartType="columnApp" >
<chart:dataacumulator dataProviderID="salesData,expenseData" />
</chart:streamed>
<chart:streamed chartType="columnApp" >
<chart:dataacumulator>
<datawebservice serviceURL="http://bigcompany.com:9011/salesXML?now" />
<datawebservice serviceURL="http://bigcompany.com:9011/salesXML?then" />
</chart:dataacumulator>
</chart:streamed>
Data Histogram Inner Tag
<chart:datahistogram .../>
<chart:streamed chartType="columnApp" >
<chart:datahistogram dataProviderID="dailyTemperatures" />
</chart:streamed>
Data Percent Change Inner Tag
<chart:datapercentchange .../>
<chart:streamed chartType="dateLineApp" >
<chart:datapercentchange dataProviderID="stockPrices" />
</chart:streamed>
Alternate Example:
<chart:streamed chartType="dateLineApp" >
<chart:datapercentchange>
<chart:dataaccumulator dataProviderID="IBMstockData,FDXStockData" />
</chart:datapercentchange>
</chart:streamed>
Data Regression Feed Inner Tag
<chart:dataregressionfeed .../>
<chart:streamed chartType="regressionApp" >
<chart:dataregressionfeed dataProviderID="windAndTemperatureData" />
</chart:streamed>
Alternate Example:
<chart:streamed chartType="regressionApp" >
<chart:dataregressionfeed>
<chart:dataaccumulator dataProviderID="windData,temperatureData" />
</chart:dataregressionfeed>
</chart:streamed>
Data Sorter Inner Tag
<chart:datasorter .../>
<chart:streamed chartType="columnApp" >
<chart:datasorter dataProviderID="salaryData" />
</chart:streamed>
Datasimulation Inner Tag
<chart:datasimulation numDatasets="2" numObservations="25" />
<chart:streamed chartType="columnApp" >
<chart:datasimulation
numDatasets="3"
numObservations="10" />
</chart:streamed>
Timedatasimulation Inner Tag
<chart:timedatasimulation numDatasets="2" numObservations="25" />
<chart:streamed chartType="candlestickApp" >
<chart:timedatasimulation
dayIncrement="7"
numDatasets="1"
numObservations="120" />
</chart:streamed>
Param Inner Tag
<chart:param name="titleString" value="hello, world" />
<chart:streamed chartType="lineApp" style="WEB-INF/myChart.properties" >
<chart:param name="backgroundColor" value="orange" />
<chart:param name="titleString" value="hello" />
<chart:param name="yAxisEnd" value="50." />
</chart:streamed>
Locale Inner Tag
<chart:locale name="localeString" value="BE_fr" />
<chart:streamed chartType="pieApp" style="WEB-INF/myChart.properties" >
<chart:locale localeString="ES_es" />
</chart:streamed>
com.ve.kavachart.utility.DataProvider Interface
public Interface com.ve.kavachart.utility.DataProvider {
/*
** Returns an Enumeration of Dataset classes.
*/
public Enumeration getDatasets();
/*
** Returns a String that uniquely identifies this data.
** Needed to make chart image caching work properly. Otherwise unnecessary.
*/
public String getUniqueIdentifier();
}
web.xml, kavachart-taglib.tld