## com.bbn.openmap.layer.shape.areas
Class AreaHandler

    java.lang.Object
      com.bbn.openmap.layer.shape.areas.AreaHandler

All Implemented Interfaces:
  PropertyConsumer

public class AreaHandler
extends java.lang.Object
implements PropertyConsumer

An object to organize graphics in a shapefile and their corresponding attributes in OpenMap. A properties object can determine how areas/graphics are to be colored, or you can grab the graphics directly and color them yourself. It's called AreaHandler because it was originally intended to be a management tool for political boundary areas, but it should work for all shapefiles, really. This object uses a CSV file created from the DBF file that usually accompanies the shapefile. Also, this class does inflict a startup burden on the map. Because all the organizational effort occurs in setProperties(), it occurs even if the handler isn't used in an active Layer.

Here is a sample of what this thing is looking for by way of properties:

                      layer.class=com.bbn.openmap.layer.shape.areas.AreaShapeLayer
                      layer.prettyName=Layer Name
                      layer.shapeFile=/usr/local/data/shape/shapefile.shp
                      layer.spatialIndex=/usr/local/data/shape/shapefile.ssx

                      # Now, provide a data file that says what the shapes in the .shp
                      # file are.  You can use the DBF file:
                      layer.dbfFile=/usr/local/data/shape/shapefile.dbf
                      # OR a csv file, created yourself or from the .dbf file.  There
                      # should be the same number of entries in the .csv file that are in
                      # the .shp file.
                      layer.csvFile=/usr/local/data/shape/shapefile.csv
                      # An attribute to tell the AreaHandler to skip over the first row
                      # of the csv file if it contains descriptive column header names.
                      layer.csvFileHasHeader=true

                      # Default DrawingAttributes properties for everything not defined
                      # specifically:
                      layer.lineColor=ff000000
                      layer.fillColor=ffff00ff

                      # Now add any other attributes accepted by the DrawingAttributes
                      # object, with the prefix as stated above, i.e. layer.lineColor)
                      #
                      # The first column index is 0, not 1.
                      #
                      # The key index specifies which column in the csv file contains
                      # unique area names that are listed in the areas list here in the
                      # properties.  In this case, it's the column that contains MA in one
                      # of its rows.
                      layer.keyIndex=4

                      # The name index is the column in the csv file that contains what
                      # should be displayed in the application when a shape is chosen - the
                      # object's proper name.
                      layer.nameIndex=4
                      layer.areas=MA RI
                      layer.areas.MA.fillColor=ffff0000
                      layer.areas.MA.lineColor=ff00ff00
                      layer.areas.RI.fillColor=ffff0000
                      layer.areas.RI.lineColor=ff00ff00

Field Summary
`protected java.util.Vector` `areasItems` The list of areas that have special coloring needs.
`static java.lang.String` `areasProperty` The property that lists special colored areas.
`static java.lang.String` `CacheFileProperty` The resource name, URL or file name of the serialized graphics file.
`protected java.net.URL` `cacheURL` The URL location of the cached graphics file.
`protected GeoCoordTransformation` `coordTransform`
`static java.lang.String` `csvFileProperty` The name of the property that holds the name of the CSV file with the area attributes, like the name and the abbreviation (or search Key).
`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.
`static java.lang.String` `dbfFileProperty` The name of the property that holds the name of the DBF file with the area attributes, like the name and the abbreviation (or search Key).
`protected DbfTableModel` `dbfModel` The DBF attribute file table model.
`protected DrawingAttributes` `drawingAttributes` Default draw parameters of the graphics that don't have something specific set for it.
`protected CSVShapeInfoFile` `infoFile` The location of the CSV attribute file.
`protected int` `keyIndex` The index of the column that holds the search key of the area.
`static java.lang.String` `keyIndexProperty` The property that specifies an index location for the area search key for a shape graphic in the database file.
`protected int` `nameIndex` The index of the column that holds the name of the area.
`static java.lang.String` `nameIndexProperty` The property that specifies an index location for the area name for a shape graphic in the database file.
`protected OMGraphicList` `omgraphics` The graphics list
`protected java.lang.String` `originalPrefix`
`protected java.util.Properties` `originalProperties`
`static java.lang.String` `pointImageURLProperty` A property that sets an image URL to use for point objects.
`protected java.util.Hashtable` `politicalAreas` The known political areas, based on the list of OMGraphics each entry contains.
`protected SpatialIndex` `spatialIndex`

Fields inherited from interface com.bbn.openmap.PropertyConsumer
`EditorProperty, initPropertiesProperty, LabelEditorProperty, ScopedEditorProperty`

Constructor Summary
`AreaHandler(SpatialIndex si, DrawingAttributes da)` Construct an AreaHandler.

Method Summary
`protected void` `checkSpatialIndexEntries(double xmin, double ymin, double xmax, double ymax, OMGraphicList retList, Projection proj)` Uses the SpatialIndex object to create the OMGraphics that fit within the boundaries.
`protected java.lang.String` `createStringFromKeyObject(java.lang.Object keyObj)` OK, we can't assume that we are assigning a string as a key, you might want to key in on a specific attribute that is a number, like the country coloring code that ESRI has in the country file.
`java.util.Hashtable` `determinePoliticalAreas(OMGraphicList graphicList)` DeterminePoliticalAreas goes over a list of omgraphics, and spits out a hashtable that holds PoliticalArea objects for every area key.
`java.util.Hashtable` `determinePoliticalAreas(OMGraphicList graphicList, java.util.Hashtable poli_areas)` DeterminePoliticalAreas goes over a list of omgraphics, and spits out a hashtable that holds PoliticalArea objects for every area key.
`OMGeometryList` `findGraphics(java.lang.String area_key)` Find the graphics that are represented by an search key.
`PoliticalArea` `findPoliticalArea(java.lang.String area_key)` Find a PoliticalArea named by the search key.
`protected java.awt.Color` `getColor(java.lang.String colorString)`
`protected java.awt.Color` `GetColorFromString(java.lang.String token)` This function would return a Color object for string such as red, green,..
`GeoCoordTransformation` `getCoordTransform()`
`DrawingAttributes` `getDrawingAttributes()`
`DrawingAttributes` `getDrawParams(int recordNumber)` Given the shapefile record number, find the drawing parameters that should be used for the shape.
`DrawingAttributes` `getDrawParamsFromCSV(int recordNumber)` Given the shapefile record number, find the drawing parameters that should be used for the shape.
`DrawingAttributes` `getDrawParamsFromDBF(int recordNumber)` Given the shapefile record number, find the drawing parameters from the DBF model that should be used for the shape.
`OMGraphicList` `getGraphics()` Get all the graphics from the shapefile, colored appropriately.
`OMGraphicList` `getGraphics(float ulLat, float ulLon, float lrLat, float lrLon)` Get the graphics for a particular lat/lon area.
`OMGraphicList` `getGraphics(float ulLat, float ulLon, float lrLat, float lrLon, Projection proj)` Get the graphics for a particular lat/lon area.
`java.lang.String` `getName(java.lang.Integer integer)` Get the name of the object at record number.
`java.lang.String` `getName(java.util.Vector vector)` Return the graphic name, given the infofile vector on the graphic.
`java.util.Hashtable` `getPoliticalAreas()`
`java.util.Properties` `getProperties(java.util.Properties props)` PropertyConsumer method.
`java.util.Properties` `getPropertyInfo(java.util.Properties props)` PropertyConsumer method.
`java.lang.String` `getPropertyPrefix()` PropertyConsumer method.
`SpatialIndex` `getSpatialIndex()`
`void` `initialize(java.lang.String prefix, java.util.Properties props)` Go through the properties, loading the shapefile, information file and attributes files, and resolve how everything should be drawn.
`void` `loadDbfModelIntoGraphics(OMGraphicList list)` This function takes an OMGraphicList and loads each one with the array representing the records in the dbf file.
`static void` `main(java.lang.String[] argv)` This main function basically reads in the data sources (the shape file and the csv information file, and creates a serialized graphics file that will act like a cache later.
`static void` `printUsage()`
`OMGraphicList` `readCachedGraphics(java.net.URL url)` Read a cache of OMGraphics
`void` `setCoordTransform(GeoCoordTransformation dataTransform)`
`void` `setDrawingAttributes(DrawingAttributes da)`
`void` `setProperties(java.util.Properties props)` Method to set the properties in the PropertyConsumer.
`void` `setProperties(java.lang.String prefix, java.util.Properties props)` Initializes this object from the given properties
`void` `setPropertyPrefix(java.lang.String pre)` PropertyConsumer method.
`void` `setSpatialIndex(SpatialIndex si)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### politicalAreas

    protected java.util.Hashtable politicalAreas

  The known political areas, based on the list of OMGraphics each entry contains.

### areasProperty

    public static final java.lang.String areasProperty

  The property that lists special colored areas.

  See Also:
    Constant Field Values

### pointImageURLProperty

    public static final java.lang.String pointImageURLProperty

  A property that sets an image URL to use for point objects. Only one image for all point objects.

  See Also:
    Constant Field Values

### keyIndexProperty

    public static final java.lang.String keyIndexProperty

  The property that specifies an index location for the area search key for a shape graphic in the database file. Default is 1. The contents of this column should match the area key used to specify the drawingattributes of that particular object as listed in these properties.

  See Also:
    Constant Field Values

### nameIndexProperty

    public static final java.lang.String nameIndexProperty

  The property that specifies an index location for the area name for a shape graphic in the database file. Default is 0.

  See Also:
    Constant Field Values

### CacheFileProperty

    public static final java.lang.String CacheFileProperty

  The resource name, URL or file name of the serialized graphics file.

  See Also:
    Constant Field Values

### csvFileProperty

    public static final java.lang.String csvFileProperty

  The name of the property that holds the name of the CSV file with the area attributes, like the name and the abbreviation (or search Key).

  See Also:
    Constant Field Values

### csvHeaderProperty

    public static final java.lang.String csvHeaderProperty

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

  See Also:
    Constant Field Values

### dbfFileProperty

    public static final java.lang.String dbfFileProperty

  The name of the property that holds the name of the DBF file with the area attributes, like the name and the abbreviation (or search Key).

  See Also:
    Constant Field Values

### areasItems

    protected java.util.Vector areasItems

  The list of areas that have special coloring needs. Used to write the properties back out.

### nameIndex

    protected int nameIndex

  The index of the column that holds the name of the area. This name will be used for display in the GUI for a particular map object.

### keyIndex

    protected int keyIndex

  The index of the column that holds the search key of the area. This is the field that is the key to use for the Hashtable holding all the area descriptions, and should be unique for each named area.

### cacheURL

    protected java.net.URL cacheURL

  The URL location of the cached graphics file.

### omgraphics

    protected OMGraphicList omgraphics

  The graphics list

### drawingAttributes

    protected DrawingAttributes drawingAttributes

  Default draw parameters of the graphics that don't have something specific set for it.

### infoFile

    protected CSVShapeInfoFile infoFile

  The location of the CSV attribute file.

### dbfModel

    protected DbfTableModel dbfModel

  The DBF attribute file table model.

### csvHasHeader

    protected boolean csvHasHeader

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

### originalProperties

    protected java.util.Properties originalProperties

### originalPrefix

    protected java.lang.String originalPrefix

### spatialIndex

    protected SpatialIndex spatialIndex

### coordTransform

    protected GeoCoordTransformation coordTransform

Constructor Detail

### AreaHandler

    public AreaHandler(SpatialIndex si,
                       DrawingAttributes da)

  Construct an AreaHandler. Needs an external SpatialIndex, and default DrawingAttributes.

Method Detail

### setDrawingAttributes

    public void setDrawingAttributes(DrawingAttributes da)

### getDrawingAttributes

    public DrawingAttributes getDrawingAttributes()

### setSpatialIndex

    public void setSpatialIndex(SpatialIndex si)

### getSpatialIndex

    public SpatialIndex getSpatialIndex()

### getPoliticalAreas

    public java.util.Hashtable getPoliticalAreas()

### setProperties

    public void setProperties(java.util.Properties props)

  Description copied from interface: `PropertyConsumer`
  Method to set the properties in the PropertyConsumer. It is assumed that the properties do not have a prefix associated with them, or that the prefix has already been set.

  Specified by:
    `setProperties` in interface `PropertyConsumer`
  Parameters:
    `props` - a properties object that the PropertyConsumer can use to retrieve expected properties it can use for configuration.

### setProperties

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

  Initializes this object from the given properties

  Specified by:
    `setProperties` in interface `PropertyConsumer`
  Parameters:
    `props` - the `Properties` holding settings for this object
    `prefix` - a String used by the PropertyConsumer to prepend to each property value it wants to look up - setList.getProperty(prefix.propertyKey). If the prefix had already been set, then the prefix passed in should replace that previous value.

### getProperties

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

  PropertyConsumer method.

  Specified by:
    `getProperties` in interface `PropertyConsumer`
  Parameters:
    `props` - 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.

### getPropertyInfo

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

  PropertyConsumer method.

  Specified by:
    `getPropertyInfo` in interface `PropertyConsumer`
  Parameters:
    `props` - 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.

### setPropertyPrefix

    public void setPropertyPrefix(java.lang.String pre)

  PropertyConsumer method.

  Specified by:
    `setPropertyPrefix` in interface `PropertyConsumer`
  Parameters:
    `pre` - the prefix String.

### getPropertyPrefix

    public java.lang.String getPropertyPrefix()

  PropertyConsumer method.

  Specified by:
    `getPropertyPrefix` in interface `PropertyConsumer`
  Returns:
    the prefix string

### initialize

    public void initialize(java.lang.String prefix,
                           java.util.Properties props)

  Go through the properties, loading the shapefile, information file and attributes files, and resolve how everything should be drawn. Might take awhile if the files are large. Called from getRectangle, which is called when the AreaShapeLayer is added to the map.

  Parameters:
    `prefix` - property file entry header name
    `props` - the properties to look through.

### readCachedGraphics

    public OMGraphicList readCachedGraphics(java.net.URL url)
                                     throws java.io.IOException

  Read a cache of OMGraphics

  Throws:
    `java.io.IOException`

### getGraphics

    public OMGraphicList getGraphics()

  Get all the graphics from the shapefile, colored appropriately.

### getGraphics

    public OMGraphicList getGraphics(float ulLat,
                                     float ulLon,
                                     float lrLat,
                                     float lrLon)

  Get the graphics for a particular lat/lon area.

  Parameters:
    `ulLat` - upper left latitude, in decimal degrees.
    `ulLon` - upper left longitude, in decimal degrees.
    `lrLat` - lower right latitude, in decimal degrees.
    `lrLon` - lower right longitude, in decimal degrees.
  Returns:
    OMGraphicList

### getGraphics

    public OMGraphicList getGraphics(float ulLat,
                                     float ulLon,
                                     float lrLat,
                                     float lrLon,
                                     Projection proj)

  Get the graphics for a particular lat/lon area.

  Parameters:
    `ulLat` - upper left latitude, in decimal degrees.
    `ulLon` - upper left longitude, in decimal degrees.
    `lrLat` - lower right latitude, in decimal degrees.
    `lrLon` - lower right longitude, in decimal degrees.
    `proj` - the current map projection.
  Returns:
    OMGraphicList

### checkSpatialIndexEntries

    protected void checkSpatialIndexEntries(double xmin,
                                            double ymin,
                                            double xmax,
                                            double ymax,
                                            OMGraphicList retList,
                                            Projection proj)

  Uses the SpatialIndex object to create the OMGraphics that fit within the boundaries.

  Parameters:
    `xmin` -
    `ymin` -
    `xmax` -
    `ymax` -
    `retList` -
    `proj` -

### getName

    public java.lang.String getName(java.util.Vector vector)

  Return the graphic name, given the infofile vector on the graphic. The AreaHandler knows which one is the name. Returns an empty string if something goes wrong.

### getName

    public java.lang.String getName(java.lang.Integer integer)

  Get the name of the object at record number. The record number is the shapefile record number, which is one greater than the index number. Returns an empty string if something goes wrong.

### getDrawParamsFromCSV

    public DrawingAttributes getDrawParamsFromCSV(int recordNumber)

  Given the shapefile record number, find the drawing parameters that should be used for the shape. Note, this recordNumber is the shapefile record number, which starts at one. All our indexes start at 0, so this is taken into account here. Don't make the adjustment elsewhere. Returns the default coloring if the key for the drawing parameters isn't found.

### getDrawParamsFromDBF

    public DrawingAttributes getDrawParamsFromDBF(int recordNumber)

  Given the shapefile record number, find the drawing parameters from the DBF model that should be used for the shape. Returns the default coloring if the key for the drawing parameters isn't found.

### createStringFromKeyObject

    protected java.lang.String createStringFromKeyObject(java.lang.Object keyObj)

  OK, we can't assume that we are assigning a string as a key, you might want to key in on a specific attribute that is a number, like the country coloring code that ESRI has in the country file. We're going to assume that if the number has an integer value, it shouldn't have decimal places. That is, a 1.0 will be truncated to 1, because that makes more sense in a data file where you are using a key as a factor. If the double value doesn't match the integer value, though, we'll assume that's what was meant and leave it alone.

### getDrawParams

    public DrawingAttributes getDrawParams(int recordNumber)

  Given the shapefile record number, find the drawing parameters that should be used for the shape. Returns the default coloring if the key for the drawing parameters isn't found.

### loadDbfModelIntoGraphics

    public void loadDbfModelIntoGraphics(OMGraphicList list)

  This function takes an OMGraphicList and loads each one with the array representing the records in the dbf file. Each graphics stores the graphic in its object slot.

### findPoliticalArea

    public PoliticalArea findPoliticalArea(java.lang.String area_key)

  Find a PoliticalArea named by the search key. If the shapefile is large, the first query will take a little extra time on the first query to read in the files.

  Parameters:
    `area_key` - the lookup key, of which the index for the column was designated in the properties file.

### findGraphics

    public OMGeometryList findGraphics(java.lang.String area_key)

  Find the graphics that are represented by an search key. If the shapefile is large, the first query will take a little extra time on the first query to read in the files.

  Parameters:
    `area_key` - the lookup key, of which the index for the column was designated in the properties file.

### determinePoliticalAreas

    public java.util.Hashtable determinePoliticalAreas(OMGraphicList graphicList)

  DeterminePoliticalAreas goes over a list of omgraphics, and spits out a hashtable that holds PoliticalArea objects for every area key.

  Parameters:
    `graphicList` - the list of graphics. The top level graphic entries on the list represent areas.

### determinePoliticalAreas

    public java.util.Hashtable determinePoliticalAreas(OMGraphicList graphicList,
                                                       java.util.Hashtable poli_areas)

  DeterminePoliticalAreas goes over a list of omgraphics, and spits out a hashtable that holds PoliticalArea objects for every area key. When an ID is found in the graphics, it is checked in the hashtable for like graphics, and added to that PoliticalArea if found. If not found, a new PoliticalArea is created and placed in the Hashtable. This will duplicate graphics if you call it more than once for the same graphic list.

  Parameters:
    `graphicList` - the list of graphics. The top level graphic entries on the list represent areas.

### getColor

    protected java.awt.Color getColor(java.lang.String colorString)

### GetColorFromString

    protected java.awt.Color GetColorFromString(java.lang.String token)

  This function would return a Color object for string such as red, green,.. (all that are available from java.awt.color class). It can also return a specific color represented by HEX or Octal number like 0xffeeffee

### getCoordTransform

    public GeoCoordTransformation getCoordTransform()

### setCoordTransform

    public void setCoordTransform(GeoCoordTransformation dataTransform)

### main

    public static void main(java.lang.String[] argv)

  This main function basically reads in the data sources (the shape file and the csv information file, and creates a serialized graphics file that will act like a cache later.

### printUsage

    public static void printUsage()

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