com.bbn.openmap.layer.location.csv
Class CSVLocationHandler

java.lang.Object
  com.bbn.openmap.MapHandlerChild
      com.bbn.openmap.OMComponent
          com.bbn.openmap.layer.location.AbstractLocationHandler
              com.bbn.openmap.layer.location.csv.CSVLocationHandler

All Implemented Interfaces:

LocationHandler, LightMapHandlerChild, PropertyConsumer, java.beans.beancontext.BeanContextChild, java.beans.beancontext.BeanContextMembershipListener, java.util.EventListener

Direct Known Subclasses:

CSVLinkHandler

public class CSVLocationHandler
extends AbstractLocationHandler
implements LocationHandler

The CSVLocationLayer is a LocationHandler designed to let you put data on the map based on information from a Comma Separated Value(CSV) file. It's assumed that the each row in the file refers to a certain location, and that location contains a name label, a latitude and a longitude (both in decimal degrees).

The individual fields must not have leading whitespace.

The CSVLocationLayer gives you some basic functionality. The properties file lets you set defaults on whether to draw the locations and the names by default. For crowded layers, having all the names displayed might cause a cluttering problem. In gesture mode, OpenMap will display the name of each location as the mouse is passed over it. Pressing the left mouse button over a location brings up a popup menu that lets you show/hide the name label, and also to display the entire row contents of the location CSV file in a Browser window that OpenMap launches.

If you want to extend the functionality of this LocationHandler, there are a couple of methods to focus your changes: The setProperties() method lets you add properties to set from the properties file. The createData() method, by default, is a one-time method that creates the graphic objects based on the CSV data. By modifying these methods, and creating a different combination graphic other than the CSVLocation, you can create different layer effects pretty easily.

The locationFile property should contain a URL referring to the file. This can take the form of file:/myfile.csv for a local file or http://somehost.org/myfile.csv for a remote file.

In the openmap.properties file (for instance):

 
 
 
       # In the section for the LocationLayer:
       locationLayer.locationHandlers=csvlocationhandler
       
       csvlocationhandler.class=com.bbn.openmap.layer.location.csv.CSVLocationHandler
       csvlocationhandler.locationFile=/data/worldpts/WorldLocs_point.csv
       csvlocationhandler.csvFileHasHeader=true
       csvlocationhandler.showNames=false
       csvlocationhandler.showLocations=true
       csvlocationhandler.nameIndex=0
       csvlocationhandler.latIndex=8
       csvlocationhandler.lonIndex=10
       # Optional property, if you have a column in the file for URLs of
       # images to use for an icon.
       csvlocationhandler.iconIndex=11
       # Optional property, URL of image to use as marker for all entries in
       # csv file without a URL listed at the iconIndex.
       csvlocationhandler.defaultIconURL=/data/symbols/default.gif
       # Optional property, if the eastern hemisphere longitudes are negative.  False by default.
       csvlocationhandler.eastIsNeg=false
       
       # CSVLocationHandler has been updated to have regular DrawingAttribute properties for both name and location.
      csvlocationhandler.name.lineColor=FF008C54
      csvlocationhandler.location.lineColor=FFFF0000
      csvlocationhandler.location.fillColor=FFaaaaaa
      csvlocationhandler.location.pointRadius=3
      csvlocationhandler.location.pointOval=true
      
      # optional, can be used if you override createLocation and need access to varying rendering attributes.
      # ra1, ra2 and ra3 would be used as keys in renderAttributes map.  All GraphicAttributes properties are available, not
      # just lineColor.
     
      csvlocationhandler.renderAttributesList=ra1 ra2 ra3
      csvlocationhandler.ra1.lineColor=0xFFFF0000
      csvlocationhandler.ra2.lineColor=0xFF00FF00
      csvlocationhandler.ra3.lineColor=0xFF00FFFF
 
 

Field Summary

protected javax.swing.Box	box
protected boolean	csvHasHeader Flag that specifies that the first line consists of header information, and should not be mapped to a graphic.
static java.lang.String	csvHeaderProperty Set if the CSVFile has a header record.
protected java.lang.String	defaultIconURL
static java.lang.String	DefaultIconURLProperty Property to set an URL for an icon image to use for all the locations that don't have an image defined in the csv file, or if there isn't an icon defined in the csv file for any of the locations and you want them all to have the same icon.
protected boolean	eastIsNeg Are east values really negative with this file?
static java.lang.String	eastIsNegProperty The property describing whether East is a negative value.
protected int	iconIndex Index of column in CSV to use as URL of the icon.
static java.lang.String	IconIndexProperty Property to use to designate the column of the CSV file to use as an icon URL
protected int	latIndex Index of column in CSV to use as latitude of location.
static java.lang.String	LatIndexProperty Property to use to designate the column of the CSV file to use as the latitude.
protected java.lang.String	locationFile The path to the primary CSV file holding the locations.
static java.lang.String	LocationFileProperty The property describing the locations of location data.
protected int	lonIndex Index of column in CSV to use as longitude of location.
static java.lang.String	LonIndexProperty Property to use to designate the column of the CSV file to use as the longitude.
protected int	nameIndex Index of column in CSV to use as name of location.
static java.lang.String	NameIndexProperty Property to use to designate the column of the CSV file to use as a name.
protected QuadTree<Location>	quadtree The storage mechanism for the locations.

Fields inherited from class com.bbn.openmap.layer.location.AbstractLocationHandler

i18n, logger, RenderAttributesListProperty, zLayer

Fields inherited from class com.bbn.openmap.OMComponent

propertyPrefix

Fields inherited from class com.bbn.openmap.MapHandlerChild

beanContextChildSupport, isolated

Fields inherited from interface com.bbn.openmap.layer.location.LocationHandler

defaultLocationColorString, defaultNameColorString, forceGlobalCommand, ForceGlobalProperty, LocationPropertyPrefix, NamePropertyPrefix, readDataCommand, showdetails, showLocationsCommand, ShowLocationsProperty, showname, showNamesCommand, ShowNamesProperty

Fields inherited from interface com.bbn.openmap.PropertyConsumer

EditorProperty, initPropertiesProperty, LabelEditorProperty, ScopedEditorProperty

Constructor Summary

CSVLocationHandler()
The default constructor for the Layer.

Method Summary

protected boolean	checkIndexSettings()
protected QuadTree<Location>	createData() Look at the CSV file and create the QuadTree holding all the Locations.
protected Location	createLocation(double lat, double lon, java.lang.String name, java.lang.String iconURL, java.util.List recordList) When a new Location object needs to be created from data read in the CSV file, this method is called.
protected void	createLocation(java.util.List recordList, QuadTree<Location> qt) This is the method called by create data with a row's worth of information stuffed in the record List.
OMGraphicList	get(double nwLat, double nwLon, double seLat, double seLon, OMGraphicList graphicList) Prepares the graphics for the layer.
java.awt.Component	getGUI() Provides the palette widgets to control the options of showing maps, or attribute text.
java.util.List<java.awt.Component>	getItemsForPopupMenu(Location loc) The location layer passes a LocationPopupMenu to the handler when on of its locations has been clicked on.
java.util.Properties	getProperties(java.util.Properties props) PropertyConsumer method, to fill in a Properties object, reflecting the current values of the layer.
java.util.Properties	getPropertyInfo(java.util.Properties list) Method to fill in a Properties object with values reflecting the properties able to be set on this PropertyConsumer.
void	reloadData() A trigger function to tell the handler that new data is available.
void	setProperties(java.lang.String prefix, java.util.Properties properties) The properties and prefix are managed and decoded here, for the standard uses of the CSVLocationHandler.
protected double	tokenToDouble(java.util.List recordList, int index, double def) Scope object to double if it's a number, or return default.
protected double	tokenToDouble(java.util.List recordList, int index, double def, boolean swapSign) Scope object to double if it's a number, or return default.
protected java.lang.String	tokenToString(java.util.List recordList, int index, java.lang.String def) Scope object to String.

Methods inherited from class com.bbn.openmap.layer.location.AbstractLocationHandler

getLayer, getLocationColor, getLocationDrawingAttributes, getNameColor, getNameDrawingAttributes, getPrettyName, getPropertyPrefix, isForceGlobal, isShowLocations, isShowNames, removed, setForceGlobal, setLayer, setLocationColor, setLocationDrawingAttributes, setNameColor, setNameDrawingAttributes, setPrettyName, setProperties, setPropertyPrefix, setShowLocations, setShowNames

Methods inherited from class com.bbn.openmap.MapHandlerChild

addPropertyChangeListener, addVetoableChangeListener, childrenAdded, childrenRemoved, findAndInit, findAndInit, findAndUndo, firePropertyChange, fireVetoableChange, getBeanContext, isIsolated, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext, setIsolated

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.bbn.openmap.layer.location.LocationHandler

getLayer, getPrettyName, isForceGlobal, isShowLocations, isShowNames, removed, setForceGlobal, setLayer, setPrettyName, setShowLocations, setShowNames

Methods inherited from interface com.bbn.openmap.PropertyConsumer

getPropertyPrefix, setProperties, setPropertyPrefix

Field Detail

locationFile

protected java.lang.String locationFile

The path to the primary CSV file holding the locations.

LocationFileProperty

public static final java.lang.String LocationFileProperty

The property describing the locations of location data.

See Also:

Constant Field Values

csvHeaderProperty

public static final java.lang.String csvHeaderProperty

Set if the CSVFile has a header record. Default is false.

See Also:

Constant Field Values

quadtree

protected QuadTree<Location> quadtree

The storage mechanism for the locations.

eastIsNegProperty

public static final java.lang.String eastIsNegProperty

The property describing whether East is a negative value.

See Also:

Constant Field Values

eastIsNeg

protected boolean eastIsNeg

Are east values really negative with this file?

csvHasHeader

protected boolean csvHasHeader

Flag that specifies that the first line consists of header information, and should not be mapped to a graphic.

nameIndex

protected int nameIndex

Index of column in CSV to use as name of location.

NameIndexProperty

public static final java.lang.String NameIndexProperty

Property to use to designate the column of the CSV file to use as a name.

See Also:

Constant Field Values

LatIndexProperty

public static final java.lang.String LatIndexProperty

Property to use to designate the column of the CSV file to use as the latitude.

See Also:

Constant Field Values

LonIndexProperty

public static final java.lang.String LonIndexProperty

Property to use to designate the column of the CSV file to use as the longitude.

See Also:

Constant Field Values

IconIndexProperty

public static final java.lang.String IconIndexProperty

Property to use to designate the column of the CSV file to use as an icon URL

See Also:

Constant Field Values

DefaultIconURLProperty

public static final java.lang.String DefaultIconURLProperty

Property to set an URL for an icon image to use for all the locations that don't have an image defined in the csv file, or if there isn't an icon defined in the csv file for any of the locations and you want them all to have the same icon.

See Also:

Constant Field Values

latIndex

protected int latIndex

Index of column in CSV to use as latitude of location.

lonIndex

protected int lonIndex

Index of column in CSV to use as longitude of location.

iconIndex

protected int iconIndex

Index of column in CSV to use as URL of the icon.

defaultIconURL

protected java.lang.String defaultIconURL

box

protected javax.swing.Box box

Constructor Detail

CSVLocationHandler

public CSVLocationHandler()

The default constructor for the Layer. All of the attributes are set to their default values.

Method Detail

setProperties

public void setProperties(java.lang.String prefix,
                          java.util.Properties properties)

The properties and prefix are managed and decoded here, for the standard uses of the CSVLocationHandler.

Specified by:

setProperties in interface PropertyConsumer

Overrides:

setProperties in class AbstractLocationHandler

Parameters:

prefix - string prefix used in the properties file for this layer.

properties - the properties set in the properties file.

getProperties

public java.util.Properties getProperties(java.util.Properties props)

PropertyConsumer method, to fill in a Properties object, reflecting the current values of the layer. If the layer has a propertyPrefix set, the property keys should have that prefix plus a separating '.' prepended to each property key it uses for configuration.

Specified by:

getProperties in interface PropertyConsumer

Overrides:

getProperties in class AbstractLocationHandler

Parameters:

props - a Properties object to load the PropertyConsumer properties into.

Returns:

Properties object containing PropertyConsumer property values. If getList was not null, this should equal getList. Otherwise, it should be the Properties object created by the PropertyConsumer.

getPropertyInfo

public java.util.Properties getPropertyInfo(java.util.Properties list)

Method to fill in a Properties object with values reflecting the properties able to be set on this PropertyConsumer. The key for each property should be the raw property name (without a prefix) with a value that is a String that describes what the property key represents, along with any other information about the property that would be helpful (range, default value, etc.). This method takes care of the basic LocationHandler parameters, so any LocationHandlers that extend the AbstractLocationHandler should call this method, too, before adding any specific properties.

Specified by:

getPropertyInfo in interface PropertyConsumer

Overrides:

getPropertyInfo in class AbstractLocationHandler

Parameters:

list - a Properties object to load the PropertyConsumer properties into. If getList equals null, then a new Properties object should be created.

Returns:

Properties object containing PropertyConsumer property values. If getList was not null, this should equal getList. Otherwise, it should be the Properties object created by the PropertyConsumer.

reloadData

public void reloadData()

Description copied from interface: LocationHandler

A trigger function to tell the handler that new data is available.

Specified by:

reloadData in interface LocationHandler

checkIndexSettings

protected boolean checkIndexSettings()

createData

protected QuadTree<Location> createData()

Look at the CSV file and create the QuadTree holding all the Locations.

createLocation

protected void createLocation(java.util.List recordList,
                              QuadTree<Location> qt)

This is the method called by create data with a row's worth of information stuffed in the record List. The indexes set in the properties should describe what each entry is.

Parameters:

recordList - a record/row of data from the csv file.

qt - the Quadtree to add the Location object, created from the row contents.

createLocation

protected Location createLocation(double lat,
                                  double lon,
                                  java.lang.String name,
                                  java.lang.String iconURL,
                                  java.util.List recordList)

When a new Location object needs to be created from data read in the CSV file, this method is called. This method lets you extend the CSVLocationLayer and easily set what kind of Location objects to use based on file contents. The lat/lon/name/icon path have already been decoded from the record List.

Parameters:

lat - latitude of location, decimal degrees.

lon - longitude of location, decimal degrees.

name - the label of the location.

iconURL - the String for a URL for an icon. Can be null.

recordList - the original List of Objects in case other entries in the row should affect how the Location object is configured.

Returns:

Location object for lat/lon/name/iconURL.

tokenToString

protected java.lang.String tokenToString(java.util.List recordList,
                                         int index,
                                         java.lang.String def)

Scope object to String. If anything goes wrong the default is returned.

Parameters:

recordList - the List for the record.

index - the index of the object to fetch.

def - default value

Returns:

String value

tokenToDouble

protected double tokenToDouble(java.util.List recordList,
                               int index,
                               double def)

Scope object to double if it's a number, or return default. If anything goes wrong the default is returned.

Parameters:

recordList - the List for the record.

index - the index of the object to fetch.

def - default value

Returns:

double value

tokenToDouble

protected double tokenToDouble(java.util.List recordList,
                               int index,
                               double def,
                               boolean swapSign)

Scope object to double if it's a number, or return default. Swap the sign if needed, if east is supposed to be a negative number. If anything goes wrong the default is returned.

Parameters:

recordList - the List for the record.

index - the index of the object to fetch.

def - default value

swapSign - multiply value by -1, say, if you know that the file has negative values for eastern hemisphere longitudes (hey, I've seen it).

Returns:

double value

get

public OMGraphicList get(double nwLat,
                         double nwLon,
                         double seLat,
                         double seLon,
                         OMGraphicList graphicList)

Prepares the graphics for the layer. This is where the getRectangle() method calls to build the OMGraphicList to draw.

Specified by:

get in interface LocationHandler

Parameters:

nwLat - NorthWest latitude of area of interest.

nwLon - NorthWest longitude of area of interest.

seLat - SouthEast latitude of area of interest.

seLon - SouthEast longitude of area of interest.

graphicList - Vector to add Locations to. If null, the LocationHandler should create a new Vector to place graphics into.

Returns:

Either the OMGraphicList passed in, or the new one that was created if null.

getItemsForPopupMenu

public java.util.List<java.awt.Component> getItemsForPopupMenu(Location loc)

Description copied from interface: LocationHandler

The location layer passes a LocationPopupMenu to the handler when on of its locations has been clicked on. This is an opportunity for the handler to add options to the menu that can bring up further information about the location, or to change the appearance of the location.

Specified by:

getItemsForPopupMenu in interface LocationHandler

Overrides:

getItemsForPopupMenu in class AbstractLocationHandler

Parameters:

loc - Location that items should be provided for.

getGUI

public java.awt.Component getGUI()

Provides the palette widgets to control the options of showing maps, or attribute text.

Specified by:

getGUI in interface LocationHandler

Returns:

Component object representing the palette widgets.