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

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

All Implemented Interfaces:
  java.awt.event.ActionListener, java.util.EventListener, LocationHandler, PropertyConsumer

Direct Known Subclasses:
  CSVLinkHandler

public class CSVLocationHandler
extends AbstractLocationHandler
implements LocationHandler, java.awt.event.ActionListener

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.locationColor=FF0000
           csvlocationhandler.nameColor=008C54
           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
          # The old nameColor and locationColor properties will still work, and will take precidence over these DrawingAttribtues properties.

Nested Class Summary
`class` `CSVLocationHandler.DefaultLocationDecoder`
`static interface` `CSVLocationHandler.TokenDecoder`

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 logitude 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` `quadtree` The storage mechanism for the locations.

Fields inherited from class com.bbn.openmap.layer.location.AbstractLocationHandler
`i18n, locationDrawingAttributes, nameDrawingAttributes, propertyPrefix, zLayer`

Fields inherited from interface com.bbn.openmap.layer.location.LocationHandler
`defaultLocationColorString, defaultNameColorString, forceGlobalCommand, ForceGlobalProperty, LocationColorProperty, LocationPropertyPrefix, NameColorProperty, 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
`void` `actionPerformed(java.awt.event.ActionEvent e)` The Action Listener method, that reacts to the palette widgets actions.
`protected boolean` `checkIndexSettings()`
`protected QuadTree` `createData()` Look at the CSV file and create the QuadTree holding all the Locations.
`protected Location` `createLocation(float lat, float lon, java.lang.String name, java.lang.String iconURL)` When a new Location object needs to be created from data read in the CSV file, this method is called.
`void` `fillLocationPopUpMenu(LocationPopupMenu locMenu)` The location layer passes a LocationPopupMenu to the handler when on of its locations has been clicked on.
`java.util.Vector` `get(float nwLat, float nwLon, float seLat, float seLon, java.util.Vector 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.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.
`protected CSVLocationHandler.TokenDecoder` `getTokenDecoder()`
`protected java.lang.String[]` `readCSVLineFromFile(java.io.BufferedReader ranFile, java.lang.String[] retPaths)`
`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.

Methods inherited from class com.bbn.openmap.layer.location.AbstractLocationHandler
`getLayer, getLocationColor, getLocationDrawingAttributes, getNameColor, getNameDrawingAttributes, getPropertyPrefix, isForceGlobal, isShowLocations, isShowNames, removed, setForceGlobal, setLayer, setLocationColor, setLocationDrawingAttributes, setNameColor, setNameDrawingAttributes, setProperties, setPropertyPrefix, setShowLocations, setShowNames`

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, isForceGlobal, isShowLocations, isShowNames, removed, setForceGlobal, setLayer, 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 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 logitude 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 propery 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 createData()

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

### getTokenDecoder

    protected CSVLocationHandler.TokenDecoder getTokenDecoder()

### createLocation

    protected Location createLocation(float lat,
                                      float lon,
                                      java.lang.String name,
                                      java.lang.String iconURL)

  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.

  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.
  Returns:
    Location object for lat/lon/name/iconURL.

### readCSVLineFromFile

    protected java.lang.String[] readCSVLineFromFile(java.io.BufferedReader ranFile,
                                                     java.lang.String[] retPaths)

  Parameters:
    `ranFile` - the file to be read. The file pointer shoutd be set to the line you want read.
  Returns:
    Array of strings representing the values between the commas.

### get

    public java.util.Vector get(float nwLat,
                                float nwLon,
                                float seLat,
                                float seLon,
                                java.util.Vector graphicList)

  Prepares the graphics for the layer. This is where the getRectangle() method call is made on the location.

  Occasionally it is necessary to abort a prepare call. When this happens, the map will set the cancel bit in the LayerThread, (the thread that is running the prepare). If this Layer needs to do any cleanups during the abort, it should do so, but return out of the prepare asap.

  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 Vector passed in, or the new onw that was created.

### fillLocationPopUpMenu

    public void fillLocationPopUpMenu(LocationPopupMenu locMenu)

  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:
    `fillLocationPopUpMenu` in interface `LocationHandler`
  Overrides:
    `fillLocationPopUpMenu` in class `AbstractLocationHandler`
  Parameters:
    `locMenu` - LocationPopupMenu to add buttons to.

### 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`
  Overrides:
    `getGUI` in class `AbstractLocationHandler`
  Returns:
    Component object representing the palette widgets.

### actionPerformed

    public void actionPerformed(java.awt.event.ActionEvent e)

  The Action Listener method, that reacts to the palette widgets actions.

  Specified by:
    `actionPerformed` in interface `java.awt.event.ActionListener`

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details