<!--
$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">
</#if>
<p>
The ToolPanel is a Component that looks for components implementing
the <htmlurl url="api/com/bbn/openmap/gui/Tool.html" name="Tool">
interface.  It provides a quick interface to make tools and controls
visible and accessable.
<p>
Some of the components available are pictured above, and explained
below:
<p>
<itemize>
<item>
<sect2>OMToolSet<label id="sec-toolpanel">
<p>
The <htmlurl url="./api/com/bbn/openmap/gui/OMToolSet.html"
name="OMToolSet"> is a composite GUI JavaBean, set up to control the
view and mouse modes of the MapBean.  Any one of its parts may be
hidden from view by adjusting its properties:

<itemize>
<item>
Directional control.  Made from the <htmlurl
url="./api/com/bbn/openmap/gui/NavigatePanel.html"
name="NavigatePanel"> Bean.  This lets you pan the screen in the
direction of the button that is pressed.

<item>
Zoom buttons.  Made from the <htmlurl
url="./api/com/bbn/openmap/gui/ZoomPanel.html" name="ZoomPanel">.
This panel has two buttons - the plus (+) button zooms in (increases
scale by 2X), and the minus (-) button zooms out (decreases scale by
2X).

<item>
Scale field window. This shows the current scale setting (1:scale),
and also lets you enter a desired scale directly.
</itemize>

<item>
LayersPanel launch button.  The LayersPanel is explained <ref id="sec-layerspanel" name="here">.

<item>
Drawing Tool Launcher.  The <htmlurl
url="api/com/bbn/openmap/tools/drawing/package-summary.html"
name="Drawing Tool"> lets the users draw different graphics on the
map, and direct those graphics to layers or components that can use
them.  It uses the MapHandler to find these components.

<item>
OverviewMapHandler.  The <htmlurl
url="api/com/bbn/openmap/gui/OverviewMapHandler.html"
name="OverviewMapHandler"> is a self-contained MapBean that provides a
reference view of a source MapBean, and also provides control over the
MapBean.

<item>
MouseMode Selector.  The <htmlurl
url="api/com/bbn/openmap/gui/MouseModePanel.html"
name="MouseModePanel"> provides a way to control the <htmlurl
url="api/com/bbn/openmap/MouseDelegator.html" name="MouseDelegator">,
choosing the active <htmlurl
url="api/com/bbn/openmap/event/MapMouseMode.html"
name="MapMouseMode">.

<item>
<htmlurl url="api/com/bbn/openmap/gui/ProjectionStackTool.html"
name="Projection Stack buttons">.  The <htmlurl
url="api/com/bbn/openmap/proj/ProjectionStack.html"
name="ProjectionStack"> remembers past map projections and lets the
user go back to preious projections.  It also lets the user go forward
again.

</itemize>

<sect2>InformationDelegator<label id="sec-infodelegator">
<p>
<#if output=html>
<IMG SRC="images/whopanel.png">
</#if>
The <htmlurl url="./api/com/bbn/openmap/InformationDelegator.html"
name="InformationDelegator"> is a JavaBean used for status updates and
messages.  The <bf><ref id="sec-navmousemode"
name="NavMouseMode"></bf> uses the InformationDelegator to display the
latitude, longitude, and XY pixel location of the cursor on the
MapBean window.  Layers can use the InformationDelegator to display
one-liners, pop-up messages, and web pages.  The colored lights at the
right of the widget reflect whether particular layers are working
(red) or are finished (green).  The lights are buttons that launch the
palette for the layer it represents.

<sect2>LayersPanel<label id="sec-layerspanel">
<p>
<#if output=html>
<IMG SRC="images/layers-window.png">
</#if>
<P>
The <htmlurl url="./api/com/bbn/openmap/gui/LayersPanel.html"
name="LayersPanel"> is used to manage the display and order of the
layers in the MapBean.  This panel also lets you bring up and dismiss
the GUI controls for a layer, called layer palettes.  Some of the
buttons act on a `selected' layer.  Click on the layer name to select
it.

<itemize>
<item>
<#if output=html>
<IMG SRC="images/top.png">
</#if>
Move the selected layer to the top of the map.
<item>
<#if output=html>
<IMG SRC="images/up.png">
</#if>
The selected layer exchanges position with the one above it.
<item>
<#if output=html>
<IMG SRC="images/down.png">
</#if>
The selected layer exchanges position with the one below it.
<item>
<#if output=html>
<IMG SRC="images/bottom.png">
</#if>
Move the selected layer to the bottom of the map.
<item>
<#if output=html>
<IMG SRC="images/DeleteLayer.png">
</#if>
Delete the selected layer from the application.
<item>
<#if output=html>
<IMG SRC="images/AddLayer.png">
</#if>
Add a layer to the application.
<item>
<#if output=html>
<IMG SRC="images/layerNotSelected.png">
</#if>
Click this to add the layer to the map.
<item>
<#if output=html>
<IMG SRC="images/layerSelected.png">
</#if>
Click this to remove the layer from the map.
<item>
<#if output=html>
<IMG SRC="images/palette_off.png">
</#if>
The GUI palette for the layer is not active.  Click this to display
it.
<item>
<#if output=html>
<IMG SRC="images/palette_on.png">
</#if>
The GUI palette for the layer is active.
</itemize>



<!-- Layers and PlugIn Section -->



<sect>Layers and PlugIns<label id="sec-layers">
<p>
<htmlurl url="./api/com/bbn/openmap/Layer.html" name="Layers"> are
components that get added to the MapBean in a hierarchical stacking
order.  The map is drawn by painting the graphics of each layer
starting with the bottommost one and proceeding up the hierarchy.
Successive layers render their graphics on top of the graphics of
lower ones.
<p>
<htmlurl url="./api/com/bbn/openmap/plugin/package-summary.html"
name="PlugIns"> are components that are used by the PlugInLayer to
fetch data and prepare graphics for the map.
<p>
Layers and PlugIns are responsible for aquiring, constructing, and rendering their
own graphical data.  The <bf><ref id="sec-omgraphics"
name="OMGraphics"></bf> package provides a simple way to construct
vector and raster graphics out of geo-spatial and XY data.
<p>
They can also be interactive, by registering for mouse events and
constructing their very own GUI widget controls.
<p>
When a layer is added to the MapBean, it automatically becomes a
<htmlurl url="api/com/bbn/openmap/event/ProjectionListener.html"
name="ProjectionListener"> of the MapBean.  This means that the layer
receives notification when the <bf><ref id="sec-projection"
name="Projection"></bf> (or view) of the map changes.
<p>
To reiterate, the standard capabilities of a Layer are:
<itemize>
<item>Create, manage, and render graphical objects.  
<item>Receive and respond to mouse events over the map.
<item>Create GUI controls for additional configuration.
</itemize>

<sect1>ShapeLayer<label id="sec-shapelayer">
<p>
This is a generic layer for displaying data in <htmlurl
url="http://www.esri.com/" name="ESRI"> shapefile format.  See the
<htmlurl url="api/com/bbn/openmap/layer/shape/ShapeLayer.html"
name="ShapeLayer"> class.

<sect1>ShapePlugIn<label id="sec-shapeplugin">
<p>
A different component for handling Shape data is in the 
<htmlurl url="api/com/bbn/openmap/plugin/esri/package-summary.html"
name="esri plugin"> package.

<sect1>VPFLayer<label id="sec-vpflayer">
<p>
This is a generic layer for displaying <htmlurl
url="http://www.nima.mil/" name="NIMA"> VPF data.  See the <htmlurl
url="api/com/bbn/openmap/layer/vpf/VPFLayer.html" name="VPFLayer">
class.


<sect1>EarthquakeLayer<label id="sec-earthquakelayer">
<p>
The <htmlurl url="api/com/bbn/openmap/layer/EarthquakeLayer.html"
name="EarthquakeLayer"> displays data of recent earthquake activity.
It gets its data by querying live data feeds at the <htmlurl
url="http://www.usgs.gov/" name="USGS">.


<sect1>Raster Layers<label id="sec-raster-layers">
<p>
<itemize>
<item><htmlurl url="./api/com/bbn/openmap/layer/rpf/RpfLayer.html"
name="Raster Product Format (RPF) Layer">, which displays <htmlurl
url="http://www.nima.mil/" name="NIMA's"> CADRG and CIB data.
<item><htmlurl url="./api/com/bbn/openmap/layer/dted/DTEDLayer.html"
name="DTED Layer">, which displays NIMA's Digital Terrain Elevation
Data.
</itemize>


<sect1>Writing your own Layer or PlugIn<label id="sec-write-your-own-layer">
<p>
To write your own layer, you need to extend the <htmlurl
url="api/com/bbn/openmap/Layer.html" name="Layer"> class.  The minimum
requirement is that you override the <tt/projectionChanged()/ and
<tt/paint()/ methods.  This former method is invoked when your layer
is part of the MapBean and the view changes (e.g., when someone
recenters the map).  It is up to you to fetch and prepare your
graphics (or maybe do something else), and then <tt/repaint()/
yourself.  The easiest way to write your own layer is to derive it
from another one already cooked up.  For some simple examples see the
<htmlurl url="api/com/bbn/openmap/layer/GraticuleLayer.html"
name="GraticuleLayer"> and <htmlurl
url="api/com/bbn/openmap/layer/test/TestLayer.html" name="TestLayer">
classes.
<P>
Many layers get their data from the local disk or cdrom of the machine
that they run on, but there are others that query remote sites on the
Internet.  The <bf><ref id="sec-earthquakelayer" name="Earthquake
Layer"></bf> is a good example of live layer.
<p>
To write your own PlugIn, you can extend the <htmlurl
url="api/com/bbn/openmap/plugin/AbstractPlugIn.html"
name="AbstractPlugIn"> class, which implements the <htmlurl
url="api/com/bbn/openmap/plugin/AbstractPlugIn.html"
name="PlugIn"> interface.  You only have to implement <tt/the
getRectangle()/ method, which returns an <htmlurl
url="api/com/bbn/openmap/omGraphics/OMGraphicList.html"
name="OMGraphicList"> to the PlugInLayer.  PlugIns can also receive
MouseEvents and create a GUI palette, just like layers.  The advantage
to creating a PlugIn is that you don't have to deal with the <ref
id="sec-swingworker" name="Swing Worker"> which should be used by
layers to kick off another thread to do their work, in order not to
slow the application down.  The PlugInLayer does this for the PlugIn.

<sect2>OMGraphics<label id="sec-omgraphics">
<p>
<htmlurl url="./api/com/bbn/openmap/omGraphics/package-tree.html"
name="OMGraphics"> help you to turn your vector or raster data into
interactive graphics that can be rendered on the map canvas.
Each OMGraphic provides a simple interface to manage projecting,
rendering, and gesturing.
<p>
In general, there are three steps needed to get your data to appear on
the screen.  The OMGraphic needs to be created.  Then call
<tt/generate()/ on the OMGraphic with the current <bf><ref
id="sec-projection" name="Projection"></bf> to prepare for rendering.
Then call <tt/render()/ on the OMGraphic with the java.awt.Graphics
context.  This final step is usually performed when the <tt/paint()/
method is invoked on your layer.  To trigger the AWT painting, call
<tt/repaint()/, instead of <tt/paint()/ directly.  Note that even if
the graphic is already in XY, it still needs to be `generated' before
it is `rendered', or it will not show up on the map.
<P>
<itemize>
<item>Vector graphics
	<itemize>
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMCircle.html" name="Circle">
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMLine.html" name="Line">
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMPoly.html" name="Polygon and Polyline">
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMRect.html" name="Rectangle">
	</itemize>
<item>Raster Graphics
	<itemize>
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMBitmap.html" name="Bitmap">
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMRaster.html" name="Raster (image)">
	</itemize>
<item>Other
	<itemize>
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMGraphic.html" name="Parent Graphic">
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMText.html" name="Text">
	<item><htmlurl url="./api/com/bbn/openmap/omGraphics/OMGraphicList.html" name="Graphic List">
	</itemize>
</itemize>
<p>
The <htmlurl url="./api/com/bbn/openmap/omGraphics/OMGraphicList.html"
name="OMGraphicList"> is a unique OMGraphic: it can be used to manage
a vector of OMGraphics.  It can also contain other OMGraphicLists, so
you can create nested groupings of graphics.
<p>
And of course you can extend any of the OMGraphic classes to create
your own specific graphic or extended functionality.


<sect2>Layer GUI Palettes
<P>
Palettes are layer-specific GUI components that provide another means
to configure and interact with the layer.  The Layer interface
provides a <tt/getGUI()/ method which can be used by the layer to
return its GUI.  The OpenMap Viewer application presents a layer's
palette in an InternalFrame.  This is accessible from the <ref
id="sec-layerspanel" name="LayersPanel"> component.


<sect2>Multi-threading and the SwingWorker<label id="sec-multithreading">
<p>
When developing your own layer you should be aware of how it could
potentially affect the overall performance of OpenMap.  Specifically,
a layer should not block too long on <tt/paint()/,
<tt/projectionChanged()/, or other interface methods.  If, for
instance, your layer needs to do a lot of computation each time
<tt/projectionChanged()/ is invoked, then you should consider spawning
a thread to do the work.  This way you won't block the propagation of
<tt/projectionChanged()/ to other layers and components.  Since all
layers are Swing components, they can call <tt/repaint()/ anytime when
they've got something new to show.  So once your thread finishes doing
work, and you've got new data, you can initiate a <tt/repaint()/.
<P>
<label id="sec-swingworker">
The <htmlurl url="./api/com/bbn/openmap/util/SwingWorker.html"
name="SwingWorker"> is a class which supports spawning and managing
worker threads; Sun has a <htmlurl
url="http://java.sun.com/docs/books/tutorial/ui/swingMisc/threads.html#SwingWorker"
name="tutorial"> on the SwingWorker.  Several of our main Layers use
this service, including the <bf><ref id="sec-shapelayer"
name="ShapeLayer"></bf>.

<!--       -->

<sect>Projection<label id="sec-projection">
<p>
The <htmlurl url="api/com/bbn/openmap/proj/Projection.html"
name="Projection"> interface allows you read-only access to the
current MapBean projection.  The MapBean updates all the Layers and
other <htmlurl
url="./api/com/bbn/openmap/event/ProjectionListener.html"
name="ProjectionListeners"> when the view changes.
<p>
A Projection object is defined with:
<itemize>
<item>Latitude and longitude of the center point of the MapBean canvas
<item>Scale,
<item>Height and width of the MapBean canvas
<item>Projection type (Mercator, Orthographic, etc)
</itemize>



</article>
