openmap-arch.sgml

OpenMap是一个基于JavaBeansTM的开发工具包。利用OpenMap你就能够快速构建用于访问legacy数据库的应用程序与applets。OpenMap提供了允许用户查看和操作地理空间信息的

<!--
$Source: /cvs/distapps/openmap/doc/sgml/openmap-arch.sgml,v $
$RCSfile: openmap-arch.sgml,v $
$Revision: 1.15.2.1 $
$Date: 2004/06/25 16:11:31 $
$Author: bmackiew $

OpenMap architecture document
-->

<!doctype linuxdoc system>

<article>

<title>OpenMap Architecture
<author>BBNT Solutions LLC
<date>2 November 2001
<abstract>
This document contains information about the architecture of OpenMap,
and how to use various components of the OpenMap Toolkit.
</abstract>


<toc>
<p>
<#if output=html>
<img src="images/bigpicture.png">
</#if>

<!--       -->

<sect>Overview<label id="sec-overview">
<p>
<#if output=html>
<img src="images/overview.png">
</#if>
<p>
The <em/OpenMap Java Toolkit/ is made up of <htmlurl
url="http://java.sun.com/beans/" name="Java Bean"> components, of
which the <bf><ref id="sec-maphandler" name="MapHandler"></bf>,
<bf><ref id="sec-mapbean" name="MapBean"></bf>, and <bf><ref
id="sec-layers" name="Layer/PlugIn"></bf> components play central
roles.

<p>
OpenMap makes it easy to build your own components (layers and
plugins) that fit into the architecture to present your own data.
With OpenMap you can integrate disparate data sources to compose a
traditional overlay-based GIS.  But you are not limited to this
approach.  OpenMap can display any type of graphical data such as JPEG
images and custom-created charts and slides.  We hope that the OpenMap
platform will foster many novel data visualization applications.
<p>
The OpenMap components use only the standard Java classes provided
with the Java 2 platform, so you can be assured that OpenMap will run
anywhere supporting Java 2.  The last version of OpenMap that runs on
the JDK 1.1.X/Swing 1.1 platform is 3.7, and that version can be
downloaded from the website.
<p>
OpenMap has been integrated into various projects at BBN, and at other
companies, and for U.S. government clients.  OpenMap works well with
Java and non-Java systems, either directly embedded or distributed on
a network and communicating with standard protocols.  <em>We look
forward to hearing how you will use OpenMap!</em>

<!-- MapHandler Section -->

<sect>MapHandler<label id="sec-maphandler">
<p>
The MapHandler is the central component that lets you manage and
connect OpenMap components is a very flexible manner.  The MapHandler
can be thought of as a conceptual map, which can contain the MapBean
and other components that manage the layers, mouse events, and
projection controls.

<p>
The MapHandler is really an extended version of Java's <htmlurl
url="http://java.sun.com/j2se/1.3.0/docs/api/java/beans/beancontext/class-use/BeanContext.html"
name="BeanContext">.  The BeanContext is a mechanism that Java Beans
can use to find other beans that they can interact with.  The
extensions that the MapHandler provides is a behavior that handles
multiple cases of a <htmlurl
url="api/com/bbn/openmap/SoloMapComponent.html"
name="SoloMapComponent"> objects.  A MapHandler can only have one
instance of any SoloMapComponent class, and can have a <htmlurl
url="api/com/bbn/openmap/SoloMapComponentRejectPolicy.html"
name="rejection"> or <htmlurl
url="api/com/bbn/openmap/SoloMapComponentReplacePolicy.html"
name="replacement policy"> for actions to take when a duplicate
SoloMapComponent class is added to the MapHandler. As an example, the
MapBean is a SoloMapComponent - the MapHandler can only use one
MapBean at a time.  If your application needs more than one MapBean,
use the same number of MapHandlers, with the corresponding number of
needed SoloMapComponents.

<p>
All OpenMap components have been designed to use the MapHandler to
locate and connect to other components they need.  Other components
that either extend the <htmlurl
url="api/com/bbn/openmap/MapHandlerChild.html" name="MapHandlerChild">
class or implement it's methods can easily be integrated into the
OpenMap application framework.


 <htmlurl url="" name="">
 <htmlurl url="" name="">

<!-- MapBean Section -->


<sect>MapBean<label id="sec-mapbean">
<p>
<#if output=html>
<img src="images/mapbean.png">
</#if>
<p>
The <htmlurl url="api/com/bbn/openmap/MapBean.html" name="MapBean"> is
a drawing canvas that derives from the Swing <htmlurl
url="http://java.sun.com/products/jfc/swingdoc-api-1.1/javax/swing/JComponent.html"
name="JComponent"> class.  Because the MapBean is a Swing component,
it can be added to a Java window hierarchy like any other Swing
windowing component.  The MapBean manages a hierarchy of <bf><ref
id="sec-layers" name="layers"></bf> which can paint themselves to the
canvas and a <bf><ref id="sec-projection" name="projection"></bf>
object to manage the view.

<p>
Layers are the only component that can be added to a MapBean.  When a
Layer is added, it becomes a ProjectionListener to the MapBean, and
receives a ProjectionEvent whenever the map is panned, zoomed, or
resized.

<sect1>BufferedMapBean<label id="sec-mapbean-buffered">
<p>
The <htmlurl url="./api/com/bbn/openmap/BufferedMapBean.html"
name="BufferedMapBean"> extends the MapBean by forcing its layers to
paint their graphics into a buffer.  This drawing buffer is then
rendered whenever the AWT causes a redraw.  This dramatically
increases performance for window exposes since it avoids the
(potentially expensive) Layer painting process.  Of course if a layer
causes a redraw, then we regenerate the drawing buffer with the
graphics and render the new image.
<p>
The OpenMap Viewer application uses the BufferedMapBean instead of the
MapBean precisely because of the increased performance.


<!-- Using OpenMap Component Section -->

<sect>Using the OpenMap components<label id="sec-using">
<p>
There are several application examples available to demonstrate how to
use OpenMap components.  The OpenMap viewer is an application that can
be easily configured to add and remove components, without code
modification.  This is the best place to start using OpenMap, and the
easiest application to customize.

If you are interested in programatically using the components, there
are several other examples to demonstrate how to do this by using the
MapBean to create passive and interactive maps.

<sect1>OpenMap Viewer<label id="sec-mapbean-viewer">
<p>
The <htmlurl url="../src/openmap/com/bbn/openmap/app/OpenMap.java" name="OpenMap
Viewer"> example is the default "face" of OpenMap.  While it looks
like a complex example to start with, it's really a simple framework
that uses the MapHandler to add and connect the OpenMap components.
See the viewer <htmlurl url="user-guide.html" name="User's Guide"> for
more information.
<p>
You can <bf><ref id="sec-write-your-own-layer" name="write your own
components"></bf> that can display your data in the OpenMap Viewer.
Once you've written the layer or plugin, all you need to do is to add a
reference to it in your <htmlurl url="../openmap.properties"
name="openmap.properties"> file.  The OpenMap Viewer reads this file
to get configuration information.  The properties file has
instructions for adding layers and plugins to the application.
<p>
Likewise, you can change the look of the application by modifying the
openmap.components property in the openmap.properties file.  There are
instructions in the properties file for modifying this property, but
the main point is that changing the application does not require a
code change.  The components are defined in the openmap.properties
file and are connected at runtime.

<sect1>SimpleMap<label id="sec-mapbean-simplemap">
<p>
This is a very simple example that shows how you use the MapBean and a
layer which shows a map of the world.  This <htmlurl
url="../src/openmap/com/bbn/openmap/examples/simple/SimpleMap.java" name="example"> uses the
MapBean to create a static political map in a window with these
steps:
<itemize>
<item>Create a <htmlurl
url="http://java.sun.com/products/jfc/swingdoc-api-1.1/javax/swing/JFrame.html"
name="JFrame"> window.
<item>Create a MapBean.
<item>Create the Political boundary Layer
<item>Add the Layer to the MapBean.
<item>Add the MapBean to the ContentPane of the JFrame.
<item>Show the JFrame window.
</itemize>

<sect1>SimpleMap2<label id="sec-mapbean-simplemap2">
<p>
This <htmlurl url="../src/openmap/com/bbn/openmap/examples/simple/SimpleMap2.java"
name="example"> is a little more complicated than the previous one,
but is more usable.  It shows the same political layer along with a
background <htmlurl
url="./api/com/bbn/openmap/layer/GraticuleLayer.html"
name="graticule"> and a <htmlurl
url="../src/openmap/com/bbn/openmap/examples/simple/RouteLayer.java"
name="foreground layer"> which shows hypothetical transportation
routes.  This RouteLayer is a good example of how to extend the
<htmlurl url="./api/com/bbn/openmap/Layer.html" name="Layer.java">
class to create your own Layer (More about this <bf><ref
id="sec-write-your-own-layer" name="later"></bf> in this document).
This example program also includes OpenMap GUI widgets for navigating
around on the Map.  The steps involved in creating the program are:
<itemize>
<item>Create a <htmlurl
url="http://java.sun.com/products/jfc/swingdoc-api-1.1/javax/swing/JFrame.html"
name="JFrame"> window.
<item>Create a MapBean.
<item>Set the center and scale of the MapBean.
<item>Create the Political, Graticule, and Route layers.
<item>Add the layers to the MapBean.
<item>Create GUI widgets.
<item>Add the GUI widgets to the ContentPane of the JFrame.
<item>Add the MapBean to the ContentPane of the JFrame.
<item>Show the JFrame window.
</itemize>
<P>
Since the MapBean is a <htmlurl
url="api/com/bbn/openmap/event/PanListener.html" name="PanListener">
and <htmlurl url="api/com/bbn/openmap/event/ZoomListener.html"
name="ZoomListener">, you can create an object that produces these
events and hook it up to the MapBean in order to "drive" the map.  The
<bf><ref id="sec-toolpanel" name="ToolPanel"></bf> object generates
<htmlurl url="api/com/bbn/openmap/event/PanEvent.html"
name="PanEvents"> and <htmlurl
url="./api/com/bbn/openmap/event/ZoomEvent.html" name="ZoomEvents">
which are used to control the MapBean.

<sect1>HelloWorld<label id="sec-mapbean-helloworld">
<p>
The <htmlurl url="../src/openmap/com/bbn/openmap/examples/hello/HelloWorld.java"
name="HelloWorld"> example extends the ideas developed in the
SimpleMap2 example.  It again uses the MapBean to show a political map
of the world, but this time with a blazing "Hello World!" painted over
the map.  It also incorporates Mouse events to allow point-and-click
navigation.


<sect1>Integrating OpenMap into your own application<label id="sec-write-your-own-mapbean">
<p>
You can integrate OpenMap into your own Java application primarily by
using the MapHandler, MapBean and Layers.  We recommend that you use
the <htmlurl url="../src/openmap/com/bbn/openmap/app/OpenMap.java" name="OpenMap
Viewer application"> as an example of using the MapHandler, and add
the components you need for your application to the MapHandler.

<P>
You can use the various <htmlurl
url="./api/com/bbn/openmap/gui/package-tree.html" name="Map GUI
Beans"> in your application to control the MapBean.  To use them, you
need to add them to the MapHandler.  Here are some of the main OpenMap
components and OpenMap GUI components that can be used in your
application:

<sect2>LayerHandler<label id="sec-layerhandler">
<p>
The <htmlurl url="api/com/bbn/openmap/LayerHandler.html"
name="LayerHandler"> is a SoloMapComponent that manages the set of layers
available to the MapBean.  You can add/remove layers in the
application, turn them on and off.  It also provides layer status
information to other GUI widgets like the <ref id="sec-layerspanel"
name="LayersPanel"> and <htmlurl
url="api/com/bbn/openmap/gui/LayersMenu.html" name="LayersMenu">.

<sect2>MouseDelegator<label id="sec-mousedelegator">
<p>
The <htmlurl url="api/com/bbn/openmap/MouseDelegator.html"
name="MouseDelegator"> is a SoloMapComponent that uses <htmlurl
url="api/com/bbn/openmap/event/MapMouseMode.html" name="MapMouseModes"> to
control how mouse movement events are passed to the layers below it.
Layers subscribe to the different MapMouseModes, and when the
MouseDelegator makes one active, the subscribed layers receive the
event and have the opportunity to consume it.

<sect2>MouseModes<label id="sec-mousemodes">
<P>
In Java AWT applications, MouseEvents are sent to components which are
MouseListeners when the cursor passes over the component.  Because the
canvas of the MapBean widget is used by many different layers and
other objects, we have slightly restricted this behavior.  Instead
we've developed the notion of "MouseModes", in which MouseEvents get
delivered to listeners registered for a mode only when that mode is
active.  Because of this, layers are restricted to implementing our
<htmlurl url="./api/com/bbn/openmap/event/MapMouseListener.html"
name="MapMouseListener"> interface instead of the MouseListener
interface.
<p>
The <htmlurl url="./api/com/bbn/openmap/event/MapMouseMode.html"
name="MapMouseMode"> interface has been implemented in four default
MapMouseModes:

<itemize>
<item>
<label id="sec-navmousemode">
The <htmlurl url="./api/com/bbn/openmap/event/NavMouseMode.html"
name="NavMouseMode"> manages MouseEvents that recenter or zoom the
MapBean canvas.  Other components can register for this mode too, but
they should not interfere with the navigation handling:
<itemize>
<item>The map is recentered when the mouse is clicked in the window.  
<item>A click and drag over the window draws a box, which recenters and
adjusts the scale of the MapBean canvas to match up with the box.
</itemize>

<item>
The <htmlurl url="./api/com/bbn/openmap/event/SelectMouseMode.html"
name="SelectMouseMode"> passes MouseEvents to layers and other
components that have registered under this mode.  MouseEvents are
passed down the hierarchy until a listener "consumes" the event.

<item>
The <htmlurl url="./api/com/bbn/openmap/event/DistanceMouseMode.html"
name="DistanceMouseMode"> draws Great Circle lines on the map,
measuring distances between points.

<item>
The <htmlurl url="./api/com/bbn/openmap/event/NullMouseMode.html"
name="NullMouseMode"> doesn't do anything with mouse events.
</itemize>

<sect2>PropertyHandler<label id="sec-propertyhandler">
<p>
The <htmlurl url="api/com/bbn/openmap/PropertyHandler.html"
name="PropertyHandler"> is a SoloMapComponent that can search for and
parse openmap.properties files, directing certain properties to
components that need them.

<sect2>Environment and Debug<label id="sec-staticclasses">
<p>
The Environment and Debug classes are static classes that manage
different overall functions for applications.  The <htmlurl
url="api/com/bbn/openmap/Environment.html" name="Environment"> class
provides functions for initializing the starting projection, and for
figuring out what type of Java environment is being used for the
application.  The <htmlurl url="api/com/bbn/openmap/util/Debug.html"
name="Debug"> class is used for controlling output.  It maintains a
table that turns different Debug statements on, and can also direct
standard output and error output to log files.

<sect2>Customized Menus<label id="sec-menus">
<p>
Menus can be customized within the OpenMap framework.  At the top
level is the <htmlurl url="api/com/bbn/openmap/gui/MenuBar.html"
name="MenuBar">, which is an extension of the Java JMenuBar.  This extension
is the implementation of the MapHandlerChild methods that let it use
the MapHandler to find <htmlurl
url="api/com/bbn/openmap/gui/MenuBarMenu.html" name="MenuBarMenus">
which will be added to the MenuBar in the order in which they are
found.  The AbstractOpenMapMenu is the MapHandlerChild implementation
for menus, and by extending this class menu contents can connect with
the other OpenMap components they are controlling. The <htmlurl
url="../src/openmap/com/bbn/openmap/gui/FileMenu.java" name="FileMenu">, <htmlurl
url="../src/openmap/com/bbn/openmap/gui/ControlMenu.java" name="ControlMenu">, <htmlurl
url="../src/openmap/com/bbn/openmap/gui/NavigateMenu.java" name="NavigateMenu">,
and  <htmlurl
url="../src/openmap/com/bbn/openmap/gui/GoToMenu.java" name="GoToMenu">
can be used as examples of how to write different menus.

<sect2>ToolPanel<label id="sec-toolpanel">
<p>
<#if output=html>
<img src="images/toolbar.png">