The JeoEdit package, consisting of the JeoEditPoints
applet and the JeoEditPolygon applet,
is a set of Java visual editors for computational geometry. Their mission
is to help the computational geometry community to realize its algorithms
and theorems on the internet, by providing a flexible and easy interface
for drawing a set of points or a polygon as well as the means to communicate
this geometric information to any applet. These editors focus on user interaction
while your applet can concentrate on algorithmic calculation. All you really
have to do is to take the geometric data and run with it.
This guide will tell you how to enable your Java applet to communicate
with the JeoEdit editors. It assumes that you know what you are doing -
you should know the
basics of Java beforehand. To learn more about JeoEditPoints, check
out the JeoEditPoints applet and read its
operating manual. Similarly to learn more
about JeoEditPolygon, check out the JeoEditPolygon
applet and read its operating manual.
Finally, if you're at the School of Computer
Science at McGill University, you
may be interested in my hints on how to get Java
to work on campus.
There are two ways in which the JeoEdit package can be integrated with
your applet. First, the editors are specifically designed to be embeddable.
Many of their visual as well as functional characteristics are configurable
and either the whole editor or only its drawing canvas can be embedded in
another applet as a self-contained module. However, since currently the
editors are not JavaBeans, such a solution would call for the writing of
some custom code - contact me if this is required. The second way relies
on interapplet communication and it is a much simpler scenario for all concerned.
The user creates and edits the geometric objects, points in JeoEditPoints
or a polygon in JeoEditPolygon. The editor then acts as a server, sending
the geometric information, a list of points or a list of polygon vertices,
to all the client applets that reside on the same web page as the editor.
In order to receive this information, a client applet must be a subclass
of the JeoEditUser class and implement the receive method. The rest of this
guide will show you how this can be done.
Here are three basic steps for developing an applet which can communicate
with a JeoEdit editor:
- Download all components that you will need to deploy the editor on
your web site from either Windows archives JeoEditPointsArchive.zip
and JeoEditPolygonArchive.zip,
or UNIX archives JeoEditPointsArchive.tar
or JeoEditPolygonArchive.tar. Each
archive is approximately 300K.
- Create a web page to house your applet as well as the editor. Place
all the editor's components in the same directory as the web page. For
an example, look at the JeoEditPoints
page or the JeoEditPolygon
page.
- Create your applet. Make its main Applet class a subclass of the JeoEditUser
class, which takes care of all the details involved with interapplet communication,
and implement the receive abstract method of JeoEditUser class to process
the geometric data sent by the editor. Examine JeoEditUser.java
to see how it works. For an example of a client applet, look at PointPrinterDemo.java or PolygonPrinterDemo.java.
The advantage of using the JeoEdit editors is that they provide a flexible
and powerful self-contained interface for the user to manipulate the geometric
structures that drive your applet, leaving you free to create the applet
of your dreams without having to worry about how that interface works.
However interapplet communication is not so easy to debug, since many development
environments allow you to debug only one applet at a time. They usually
don't support debugging an applet while it is running in a web browser or
debugging multiple applets that are running concurrently and communicating
with each other. The best you can do is to create a set of text files containing
the various test cases for your applet (the output of PointPrinterDemo or
PolygonPrinterDemo may prove helpful in constructing these files). Then
to debug your applet, read in your test files in place of the data that
user would generate with a JeoEdit editor. This way, not only your applet
is easier to test, but your tests are more repeatable.
- For the editor and the client applets to be able to communicate with
each other, they all must reside on the same web page (i.e. the same HTML
file), the web browser should be aware of their existence while the editor
is running (this is a possible problem in very long HTML files), and the
web browser must implement the AppletContext.getApplets()
mechanism correctly. For more information on how interapplet communication
should work in a web browser, take a look at Sun's specifications
for the HotJava browser.
- To deploy JeoEditPoints on a web page use the HTML tag:
<APPLET CODE="RunJeoEditPoints.class"
CODEBASE="./"
NAME="JeoEditPoints"
WIDTH="400" HEIGHT="50" ALIGN="MIDDLE"
ALT="JeoEditPoints is loading...">
<PARAM NAME="ARCHIVE"
VALUE="./JeoEditPoints.jar">
<PARAM NAME="HSPACE" VALUE="10">
<PARAM NAME="VSPACE" VALUE="10">
</APPLET>
Similarly, to deploy JeoEditPolygon on a web page use the HTML tag:
<APPLET CODE="RunJeoEditPolygon.class"
CODEBASE="./"
NAME="JeoEditPolygon"
WIDTH="400" HEIGHT="50" ALIGN="MIDDLE"
ALT="JeoEditPolygon is loading...">
<PARAM NAME="ARCHIVE"
VALUE="./JeoEditPolygon.jar">
<PARAM NAME="HSPACE" VALUE="10">
<PARAM NAME="VSPACE" VALUE="10">
</APPLET>
- It is possible for multiple client applets to receive information from
a single editor. Likewise, it is possible for multiple editors to send
information to a single client applet.
- The JeoEditUser class, a subclass of Applet, must be the superclass
of every client applet. It overrides action(Event, Object) and getParameter(String) methods of the Applet class in
order to enable communication between the editor and the client applet.
If the client applet's subclass of JeoEditUser needs to override the action(Event, Object) method then it should use the
following code:
public boolean action(Event act, Object data){
if (super.action(act, data)) {
return true;
}
< process action event >
...
}
If the client applet's subclass of JeoEditUser needs to override the
getParameter(String)
method then it should use the following code:
public String getParameter(String p){
if (p.equals(JeoEditUser.usesJeoEdit)) {
return super.getParameter(p);
}
< process parameter request >
...
}
Also the client applet's subclass of JeoEditUser should never override
the run() method.
- The editor will send the geometric information to a client applet when
the user invokes the Process Task (left click on the "GO" button
in the editor), or, if the Auto-Process Option is turned on (right click
on the "GO" button in the editor), whenever the user makes a
change to the current geometric object. If the Auto-Verify Option is turned
on, the information will only be sent if it is deemed correct (a point
set should have no three points that are collinear, while a polygon should
be simple with no consecutive collinear vertices).
- The client applet receives and processes geometric information in its
own thread called requestThread, which is separate from any editor thread
or the client's AWT event processing thread. The geometric information
is not placed in a queue, hence if a client applet hasn't finished processing
the last data which the editor sent, then the editor may forego sending
new geometric data until the old data has been taken care of. If the client
crashes due to an unhandled exception while processing the geometric information,
its user interface as well as the editor should continue to work. In fact,
the editor will try to restart the requestThread before sending more information.
However, notice that processing in the client's requestThread can interfere
with processing in the client's AWT event thread (the thread which handles
the user's actions such as button clicks or key presses), so the client
applet must be designed with these issues in mind.
- Both JeoEditPoints and JeoEditPolygon describe their geometric data
as x[] and y[] arrays of doubles, with each coordinate 0.0 <= x <=
1.0 and 0.0 <= y <= 1.0, and the origin is the top left corner (the
usual Graphics origin in Java). These coordinates are not affected by the
size of the editor's window; the geometric object is scaled to fit in the
space provided for it. Hence, editors usually display the geometric object
with a rectangular aspect ratio, so the user edits the geometric object
while it typically appears slightly horizontally stretched. Only JeoEditPoints
guarantees that no two points lie on top of one another. With JeoEditPolygon,
when the Auto-Verify Option is turned on and so the polygon is checked
for simplicity before being sent, it is safe to assume that the data points
denote the polygon vertices in counterclockwise order (if the polygon isn't
simple you can only assume that the vertices are in consecutive order).
- When the editor sends the geometric information to the client applet,
its receive method will be invoked. In addition to the x[] and y[] coordinates
of the geometric data, the receive method is provided with the type of
the data being sent (point set or polygon vertices), the number of the
editor's workspace where the geometric object resides, the unique name
of the editor sending the data, and the time when the data was sent. Hence,
the client applet can process the geometric data differently, depending
on the editor or workspace it comes from (e.g. the applet calculates the
intersection of two polygons, so it demands that one polygon is created
by the user in JeoEditPolygon's workspace 1 and the other in workspace
2). Here is the receive method in detail:
public abstract void receive (double x[], double y[], long
timestamp, int workspace, int datatype, String editor, int reserved1, int
reserved2)
double x[]: 0.0 <= x[i] <= 1.0
the x coordinates of the geometric data
double y[]: 0.0 <= y[i] <= 1.0
the y coordinates of the geometric data
long timestamp: in milliseconds
the time when the geometric data was sent
int workspace: 1 <= workspace <= 5
the editor's workspace where the geometric object resides
int datatype: JeoEditUser constants
is polygonDataID if the data specifies the vertices of a polygon
is pointsDataID if the data specifies a point set
String editor: unique name of the editor sending the data
int reserved1: reserved for future use
int reserved2: reserved for future use
Wishing you lots of happy-go-lucky code...
Mark Grundland
JeoEdit Package: Copyright © 1998
Mark Grundland & Godfried Toussaint.
All rights reserved.