Using eComet with Java

From CometWiki

Contents 1 Using eComet with Java 2 Background information 3 Download information 4 Installation information (local system) 5 Behind the scenes

Using eComet with Java

This tip shows you how to use eComet with a Java applet. To best demonstrate this process, we chose a Java applet that displays a bar graph. To make things interesting, we wrote an MTB program that reads the bar chart data from a Comet file and merges it into an HTML template file – old hat for the XAP aficionados reading this. As you will soon see, the HTML template passes this data to the Java applet, which then displays a bar graph based on values from a Comet data file.

If you understood that first paragraph, you’re probably thinking, “Hey, that’s pretty cool…” If you didn’t understand it, you will by the time you’re done reading this tip.

In either case, please look at the results first. Click on this link to see the sample program in action. Don’t forget to come back to this page when you’re done.

http://signature.net:8080/xap/barchart

This example was easy to create. In fact, very little programming was required on our part. The Java applet came from Sun Microsystems (by the way, it was free). Even though Sun included the Java source code, we didn’t need it; we simply used their compiled applet with our data. We did write two small MTB programs – one to merge the data with an HTML template file and another to allow the user to edit the data – and created two HTML template files.

Background information

Java is a programming language that was invented by Sun Microsystems in 1995. When a Java source file is compiled, it becomes an “applet.” Unlike many other programming languages, though, a Java applet is not comprised of hardware-specific machine instructions. Instead, an applet is machine-independent “byte code” that can be interpreted by software running on a wide variety of platforms. This software is called a “Java Virtual Machine” (JVM). For example, both of the major web browsers now include a JVM, which makes it very easy to integrate applets with web pages. Also, a number of hardware companies are including a JVM in their portable electronic devices (cell phones, PDA’s, etc.).

Java applets are typically stored on web servers. When an HTML file calls for an applet (see details below), the applet is transferred from the server to the client and is executed in the JVM on the client. That’s exactly what happens with the BARCHART example.

When you compile a Java source file, the Java compiler creates a “class” file (another name for “applet”). The applet in the BARCHART example is a 6K program named Chart.class (and the source file is named Chart.java). As we mentioned above, this applet was written by Sun Microsystems, probably as a way to demonstrate some of Java’s capabilities. Sun now distributes this applet for free. We found it on a web site that contains many other freeware and shareware Java applets. The site is http://www.javaboutique.internet.com/. Take a look at this site and let us know if you find any other useful tools for your XAP applications.

In a way, you can think of an applet as a “compiled subroutine” for an HTML document. You call the subroutine by including an <APPLET> tag in the HTML file. Some applets are designed so the HTML document can pass arguments to them – this is accomplished with the <PARAM> tag. These tags are explained in detail below.

The BARCHART demo program uses four technologies: HTML, JavaScript, XAP (eComet), and Java.

• · The HTML code defines the text and form controls (radio buttons) on the sample page.

• · The JavaScript code streamlines one facet of the sample page – the radio buttons. The sample page contains radio buttons, but does not contain a “submit” button. When the user clicks on a radio button, the form data is immediately submitted to the server. This is accomplished by adding a JavaScript event handler named onClick to the HTML tag for each radio button. The code (a combination of HTML and JavaScript) looks like this:

<FORM METHOD="POST" ACTION="XAP-server-name/BARCHART">
<INPUT TYPE="radio" NAME="YEAR" VALUE="1988" onClick="submit()">
<INPUT TYPE="radio" NAME="YEAR" VALUE="1989" onClick="submit()">
<INPUT TYPE="radio" NAME="YEAR" VALUE="1990" onClick="submit()">
<INPUT TYPE="radio" NAME="YEAR" VALUE="1991" onClick="submit()">
etc.
</FORM>

By the way, JavaScript was invented by Netscape Corporation (not Sun Microsystems). It is a scripting language that enhances the capabilities of HTML. It is not the same thing as Java, despite the fact that the products are named so similarly.

• · Clicking one of the radio buttons causes the form data to be sent to the BARCHART program (an MTB object program) on the XAP server named in the ACTION parameter of the FORM tag. For example, if you want to send the data to Signature's XAP server (using port 8080), the FORM tag would look like this:

<FORM METHOD="POST" ACTION="http://signature.net:8080/xap/BARCHART">

Or, if you wanted to run this example on a local XAP server (using port 80, the default), the FORM tag would look like this:

<FORM METHOD="POST" ACTION="http://127.0.0.1/xap/BARCHART">

The BARCHART program performs the following steps:

• 1. Retrieve the data from the HTML form (the YEAR and ORIENTATION fields) by reading the CGI interface file

• 2. Open the Comet data file containing the data to be graphed

• 3. Read a record from that file (the key of which is the YEAR field)

• 4. Close the data file

• 5. Set the values of the merge fields (including the colors for the bars in the graph)

• 6. Merge the data with an XAP HTML template file

Clicking on the “Edit” button causes the form data to be sent to another MTB program on the XAP server. This program is named BAREDIT, and it lets you edit the temperature data for a given year.

• · The Java applet draws the bar graph. To use this applet, include an <APPLET> tag in your HTML file. You'll need to specify information about the Java program as well as the data values needed by that program. For example:

<applet codebase="http://www.signature.net/javademo" code="Chart.class" height=300 width=500>
. 
.
.
</applet>

The above tag tells the browser that it will be executing a Java applet named Chart.class which is located at [1], and that the applet's output will be displayed on a section of the web page measuring 300 x 500 pixels.

The Chart.class applet requires certain parameters, including general information about the bar graph as well as the data values that are to be drawn. These values are specified with the <PARAM> tag within the <APPLET> section. Here's a sample:

<applet codebase="http://www.signature.net/javademo" code="Chart.class" height=300 width=500>
<param name=title value="Average monthly temperatures for 1988">
<param name=columns value="12">
<param name=orientation value="horizontal">
<param name=scale value="4">
<param name=c1_label value="January">
<param name=c1 value="40">
<param name=c1_color value="cyan">
<param name=c1_style value="solid">

<param name=c2_label value="February">
<param name=c2 value="33">
<param name=c2_color value="blue">
<param name=c2_style value="solid">

<param name=c3_label value="March">
<param name=c3 value="42">
<param name=c3_color value="cyan">
<param name=c3_style value="solid">

.
.
.
</applet>

The following table describes all of the parameters used by the Chart.class applet:

Parameter	Description
title	A title that is displayed at the bottom of the bar graph
columns	Number of columns to be graphed
orientation	Orientation of the graph. Valid values are: "horizontal" "vertical"
scale	An integer representing the scaling factor for the graph
cn	An integer data value for column n (examples: c1, c2, c3, c4) Note: In the sample program, this value is the average monthly temperature, such as: <param name=c1 value="40"> <param name=c2 value="33"> <param name=c3 value="42">
cn_label	Text label for column n (examples: c1_label, c2_label) For example: <param name=c1_label value="January"> Note: In this example, the MTB program evaluates the ORIENTATION value and chooses the text accordingly: Horizontal values “January” “February” “March” “April” “May” “June” “July” “August” “September” “October” “November” “December” Vertical values (shorter in order to keep the bars narrow) “Jan” “Feb” “Mar” “Apr” “May” “June” “July” “Aug” “Sept” “Oct” “Nov” “Dec”
cn_color	Color of the bar for column n. (examples: c1_color, c2_color) For example: <param name=c1_color value="blue"> Valid values are: "red" "green" "blue" "pink" "orange" "magenta" "cyan" "white" "yellow" "gray" "darkGray" Note: In this example, the MTB program evaluates the temperature for each month and assigns the color based on the following rules: Less than 40 degrees = blue 40 to 49 degrees = cyan 50 to 59 degrees = green 60 to 69 degrees = orange 70 to 79 degrees = yellow Greater than or equal to 80 degrees = red
cn_style	Style for column n (examples: c1_style, c2_style) For example: <param name=c1_style value="solid"> Valid values are: "solid" "striped"

Download information

The files comprising this example are available for download at http://www.signature.net/download/demos.

The following table describes the files contained in BARCHART.ZIP:

File	Description
barchart.htm	HTML template file that calls the Chart.class applet, and sends form data (radio buttons) to barchart.obj
barchart.mtb	MTB source code for barchart.obj (text file)
barchart.obj	eComet object program that receives form data, reads Comet keyed file, and merges data into HTML template file (must be placed in the XAP directory)
baredit.htm	HTML template file that displays data for editing purposes
baredit.mtb	MTB source code for baredit.obj (text file)
baredit.obj	eComet object file that displays data for editing purposes and writes edited data back to data file (must be placed in the XAP directory)
bardata bardata.i00	Sample Comet data file containing average monthly temperatures for 1988 through 2000 Keyed file Record size = 28 Key size = 4
Chart.class	Java applet that displays bar chart
Chart.java	Java source code for Chart.class (not required)

Installation information (local system)

Follow these instructions to install the BARCHART files on a local XAP system (IP address of 127.0.0.1):

1. Unzip the BARCHART.ZIP files as follows:

· Put the HTML template files (barchart.htm and baredit.htm) in a working directory such as c:\html

· Put the MTB source programs (barchart.mtb and baredit.mtb) in a Comet directory (the examples contain a directory name of “MSC”)

· Put the Comet data file (bardata and bardata.i00) in a Comet directory

· Put the eComet object programs (barchart.obj and baredit.obj) in the XAP directory

· Put the Java applet (Chart.class) in a working directory such as c:\html

· The Java source code (Chart.java) is not required

2. Using a text editor, open the barchart.mtb source code. Look for the SET statements that set the following symbolic constants:

HTMLPATH$

XAPCODEBASE$

JAVACODEBASE$

Set these values to match the locations where you installed the barchart.obj file (HTMLPATH$), the barchart.htm template file (XPACODEBASE$), and the Chart.class Java applet (JAVACODEBASE$). See the MTB source program for the required formats.

3. Verify that the conditional compile directive (at the beginning of the program) is set to compile on a local system. Compile barchart.mtb, making sure to put the object program in the XAP directory.

4. Using a text editor, open the baredit.mtb source code, looking for the following symbolic constants:

HTMLPATH$

XAPCODEBASE$

Set these values to match the locations where you installed the baredit.obj file (HTMLPATH$) and the baredit.htm template file (XPACODEBASE$). See the MTB source program for the required formats.

5. Verify that the conditional compile directive (at the beginning of the program) is set to compile on a local system. Compile baredit.mtb, making sure to put the object program in the XAP directory.

6. Start the XAPMON program on your local eComet server.

7. From a web browser, launch the BARCHART program, as follows:

http://127.0.0.1/xap/barchart

Behind the scenes

To fully understand how these programs and templates interact with each other, look at the following files:

· Study the barchart.htm template file. Notice all of the merge fields, some of which are parameters for the radio buttons and associated <FORM> tag, and others of which are parameters for the Java applet. All of these merge fields are replaced by actual values that are determined by the barchart.obj program.

· Study the barchart.mtb source program to see how the merge field values are determined. When this program starts, it attempts to read the YEAR and ORIENTATION fields from the CGI interface file. If these values are not found (indicating that the program running for the first time), default values of “2000” and “H” are set. This program then reads data from the “BARDATA” file, in order to get the average monthly temperatures for the given year. The subsequent statements determine the values of and write the merge fields to the CGI interface file.

Besides writing the monthly temperatures, the program also writes other values such as the bar chart colors, the bar labels (“January” vs. “Jan”), orientation (“horizontal” vs. “vertical”). The program also writes “CHECKED” next to the appropriate radio buttons (one for the year, one for the orientation), which provides a way for the user to know which value was selected and which value will be submitted when another radio button is clicked.

Finally, this program merges the HTML template file with the CGI interface file, which displays the web page. (Of course, the web page contains an <APPLET> tag, which executes the Chart.class applet and displays the bar graph.)

· Study baredit.htm and baredit.mtb to see how the editing routine works. The baredit.htm program is multi-purpose; it is designed to read a data record and merge the contents into a template file, as well as read the data from the CGI interface file and update the data file.

· If you're curious, take a look at the Java source code Chart.java. Even if you don't know Java, you can easily see the parameters and their values, along with the general organization of the code.