Step
1 - Load the Servlet Class files into your Servlet Engine
In order to use the Pie Chart servlet you will need to have
a servlet engine already setup and configured on your web
server. There are a wide variety of servlet engines available
and as such specific details for each engine are beyond
the scope of this documentation. As such we will limit this
discussion to the following two engines,
Tomcat
- for full details see http://jakarta.apache.org/tomcat/
Servletrunner
( runs on the local machine as part of the JSDK environment
)
see http://java.sun.com/products/servlet/
The
first step is to place the following class files and the
'encoder' directory in your Servlet Engines class file directory.
For Tomcat this is usually /WEB-INF/classes/ and for the
default setup of the JSDK environment this is the /examples/
directory.
piecharts.class
PieChartServlet.class
encoder
(these
classes & directory can be found in the Servlet directory
).
Notes
:
-
The servlet utilizes an Image encoder in order to produce
the graph image.
-
It is also vital that a graphics environment exists on
your server, for Microsoft Windows based servers this
is always the case however for UNIX and Linux it is important
that the X11 environment is in operation. If for whatever
reason a graphics environment is not present on your server
then you may wish to consider the PJA ( Pure Java AWT
) alternative - for full details on this click
here.
Step
2 - Set up the Configuration data.
The pie chart servlet provides the following two options
for inputting the configuration data.
a)
Configuration File.
The servlet will read all the configuration parameters
from a specified file. To use this option incorporate
the url of the configuration file into the the IMG tag
(see Step 4).
The
"pieprops.txt" file contained in this directory
is an example file containing the configuration data (
click
here to view the example file ). As you will see from
the example file each property is specified on a name,
value basis. Note that comments may be added to this file
by placing "<!--" at the beginning of a line.
Adjust the property values to specify the characteristics
of the pie graph and then place this file in the same
directory as your web page.
For
a full description of each property please see the "Configuration
Options and Parameters".
b)
Server Side process
This option allows the pie graph servlet to obtain
all the configuration data from a server side application.
The server side script should be designed to output the
configuration data in the same format as the file in option
a) above.
As
with the previous option the URL of the server side process
is specified in the <IMG> tag of your HTML page
(see Step 4).
For
an example script see PieConfigServlet.java
in the ServerTemplateScripts directory.
For
most implementations supplying the configuration data
from a data file will be the most efficient, however supplying
this data via a server side script is useful where you
wish to hold this data in a database. A server side script
would then be used to read the config data from the database
and then supply to the servlet at runtime.
Step
3 - Set up the Pie Chart data
As with the configuration data there are three options for
supplying the data values to the servlet,
a)
Data File.
The servlet will read all the data from a specified file.
To use this option incorporate the url of the data file
into the the IMG tag (see Step 4).
The
"piedata.txt" file contained in this directory
is an example file containing the data ( click
here to view the example file ). As you will see from
the example file each piece of data is specified on a
name, value basis. Note that comments may be added to
this file by placing "<!--" at the beginning
of a line.
Simply create a similar file adding your data in the values.
For a full explanation of this file please see the "Retrieving
Data from Files" under the "Data and Configuration"
section ( or click here).
b)
Server Side process
This option is the most powerful and gives the servlet
the ability to retrieve data from databases. This method
involves specifying a server side script in the <IMG>
tag of the html page (see Step 4) which in turn returns
the data to the graph servlet, giving enormous flexibility
for data acquisition. The server side script can be constructed
in the language of your choice and as such can be written
to acquire data from the widest variety of sources, multiple
databases etc.
To
instruct the servlet to retrieve data from a server side
script simply add the URL of your server side script into
the <IMG> tag of the HTML page (see Step 4). The
server side script should be designed to output the data
in the same format as the file in option a) above (ie.
first 20 character positions of each line specify the
data name, whilst positions 21 onwards specify the value).
For
an example script see PieDataServlet.java
in the ServerTemplateScripts directory.
For
a full description of constructing a server side script
which retrieves data from a database see the section "Connecting
the Graph to a database" under the "Data and
Configuration" section ( or click
here).
Step
4 - Incorporate the Servlet IMG tag into your HTML page.
The final step is to incorporate the graph into your HTML
page. This is done via the standard html <IMG> tag.
<img
src="[ServletEngineURL]/PiechartServlet?
config=[URLconfigFile]&
data=[URLdataFile]"
width="500" height="420">
Where,
[ServletEngineURL]
should be replaced
with the url for your servlet engine. If running ServletRunner
on your local machine this would be, http://localhost:8080/servlet/
[URLconfigFile]
should be replaced
with the URL to either a Configuration file or server side
process.
[URLdataFile]
should be replaced
with he URL to either a Data file or server side process.
For
example if we have the following,
Servlet
Engine URL = http://www.jpowered.com/servlet/
Configuration File URl = http://www.jpowered.com/pie_chart/config.txt
Data Servlet = dataservlet.class
producing a graph
image of 400 pixels by 300 pixels, we would incorporate
the following <IMG> tag into our html page,
eg.
<img
src="http://www.jpowered.com/servlet/PiechartServlet?
config=http://www.jpowered.com/pie_chart/config.txt&
data=http://www.jpowered.com/siriusjava/servlet/dataservlet"
width="400" height="300">
If you
experience any difficulties implementing then please do
not hesitate to contact us at,
support@jpowered.com