org.eclipse.ohf.stem.internal.data.utility
Class NeighborUtility

java.lang.Object
  extended by org.eclipse.ohf.stem.internal.data.utility.NeighborUtility

public class NeighborUtility
extends java.lang.Object

NeighborUtility generates the CommonBorder property file.

 NeighborUtility has to run as an Eclipse Plugin application 
 because it uses Platform.LatLongProvider to process the 
 LatLong xml files and it will only run in a plugin environment.
 
 *** NOTE ***
   The path for the Eclipse workspace is hardcoded below.
   Change the value for "baseFolder" to reflect your environment.
   Also the output is generated in whereever your system defines 
   as the "Temporary" folder.  You would then copy the files to 
     org.eclipse.ohf.stem.internal.data 
        resources/data/relationship/commonborder 
   and commit them to CVS.
   
 To generate the required launch script:
   
  - From PackageExplorer, RightClick src for NeighborUtilityTest
  - Select RunAs->JUnit Plug-in Test
    It should startup a new image of Eclipse, run NeighborUtility 
    and terminate.  The console output should indicate any errors.
    
 
 To make it easier to invoke, we use the JUnit plugin environment
 to setup the plugin environment and invoke the following 
 NeighborUtilityTest. 
 NeighborUtilityTest will invoke the following methods in MeighborUtility
 
   doAllInternal  - creates neighbor list for the admin 1 or 2 areas in 
                    each country. creates CCC_2_CCC_2.properties where 
                    CCC is the country code. 
                    
   doWorld        - creates a list of neighboring countries from the 
                    list of all countries. creates ZZZ_0_ZZZ_0.properties
 
   doAllBorders    - uses ZZZ_0_000.properties to identify neighboring 
                     countries and builds bordering neighbor lists 
                     from the admin 2 (or admin 1) areas in each country.
                     
                     
 The methods setBBox and ProcessBBox do the actual processing. 
 
 
  API for setBBox and processBBox
   //Interate through the nodes.
    for (final Iterator nodeIter = canonicalGraph.getNodes().values()
        .iterator(); nodeIter.hasNext();) {
        final Node node = (Node) nodeIter.next();
        final LatLongProvider latLongProvider = (LatLongProvider) LatLongProviderAdapterFactory.INSTANCE
            .adapt(node, LatLongProvider.class);
  //The node may or may not have lat/long data associated with
  //it, if it doesn't the list that's returned will be empty.
      final LatLong latLong = latLongProvider.getLatLong();
  //Now for each node we create a BoundingBox for each polygon 
  //  and call setBBox to save the BoundingBox in a map.                                
      String name = node.getDublinCore().getTitle();
      NeighborUtility.setBBox(map,bbox);
     } // for
  // We now have a map of AdminArea for one country and another map for 
  // for the neighboring country    
  //Now we call the processBBox method to do the processing
  // BBox1 is adjacent to BBox2 if any of the corners of BBox1 is contained
  // in BBox2 or any corner of BBox2 is contained in BBox1
  // if that is true they they might be neighbors and we check further
  // We compare all of the points of Polygon1 to match against polygon2
  // If we find a match then they are neighbors.
  //
  // If no match try again this time looking for points that match within 
  // a small delta. 
   
  // ifstill not match we make one more try, 
  // check if any of the points for 
  // polygon1 are contained inside polygon2 or visaversa. 
  
      List list = NeighborUtility.processBBox(bbox1,bbox2);
      -> testAdjacency(bbox1,bbox2)  test AdminArea containment
      -> testAdjacencyMatch(bbox1,box2) Test if points match  
      
  // The resulting ArrayList contains an array of 2 Strings , each
  // representing 2 neighboring areas.  
  // We then call the writeProperties method to write the 
  // properties file.
      writeProperties(list,admin0a,admin0b);
  // The properties files will be written to the temporary directory
  // On Windosw:  c:/tmp/commonborders/CCC_2_XXX_2.properties    
  //
     It needs to be copied to org.eclipse.ohf.stem.internal.data
          /resources.data/relationship/comonborder 
     and then checked into CVS/SVN     
  


Nested Class Summary
static class NeighborUtility.AdminArea
          Class used to hold both the polygon and bounding box so it can be stored in a HashMap and passed around to methods that need both.
 
Field Summary
static java.lang.String baseFolder
          Hardcoded File reference to the above URI Needed becasue we don;t know how to convert a URI to a file path
static java.lang.String baseURI
          URI reference to the LatLong data baseURI/country/CCC/CCC_0_MAP.xml
static boolean bboxCheckOnly
          if true then only check for neighbors using BBox check This is used for generating the ZZZ world list.
static java.lang.String commonborderFolder
          Hardcoded File reference to the commonborder property files.
static boolean DEBUG
          if true then debug info can be written
static java.lang.StringBuffer problems
          Used to build an error message for neighbors with no commonborder
static java.lang.String workspaceFolder
          User 's unique folder where they keep all of the STEM code.
 
Constructor Summary
NeighborUtility()
           
 
Method Summary
static boolean closeTo(double lt1, double ln1, double lt2, double ln2)
          Check if point1 is close to point 2 by the amount of the delta.
static void debug(java.lang.String msg)
          print debug messages to the r log.
static void debug(java.lang.String msg, java.lang.Throwable e)
          debug output for exceptions
static boolean doAllBorders(PlatformLatLongDataProvider fixture, java.util.List<java.lang.String[]> worldList)
          This will generate a list of neighbors for all neighboring countries.
static java.lang.String getAdmin(java.lang.String admin0)
          Get the file name for the most detailed admin area for the specified admin 0
static java.lang.String getAdmin0(java.lang.String admin0)
          Get the file name for the admin0 file (or admin1 if admin0 does not exist)
static java.lang.String getPropertyFolder()
          get the folder to use for output.
static java.util.List<java.lang.String[]> matchArea(java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map1, java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map2)
          After all the latLong data has been submitted this method is called to generate the list of neighbors between the first set of Admin areas and the 2nd
static void output(java.lang.String msg)
          print messages to the log.
static java.util.List<java.lang.String[]> processAreas(java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map)
          After all the latLong data has been submitted this method is called to generate the list of internal neighbors from this Map of AdminAreas.
static void setArea(java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map, java.lang.String id, LatLong latLong)
          Called to input another LatLong object This builds a Map of latlong areas for an admin area
static void statistics()
          print the statistics
static boolean testAdjacency(NeighborUtility.AdminArea bbox1, NeighborUtility.AdminArea bbox2)
          Test adjacency by containment of any corner of two bounding boxes If any corner of AdminArea 1 is contained in AdminArea 2 or any corner of AdminArea 2 is contained in AdminArea 1 then they are adjacent.
static boolean testAdjacencyContains(NeighborUtility.AdminArea bbox1, NeighborUtility.AdminArea bbox2)
          Test adjacency by checking if any point on the border of one area is contained in the polygon for the other area
static boolean testAdjacencyMatch(NeighborUtility.AdminArea area1, NeighborUtility.AdminArea area2)
          Test adjacency by matching the points on the border of each area for a match
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

workspaceFolder

public static java.lang.String workspaceFolder
User 's unique folder where they keep all of the STEM code. ******* Must be changed *****


DEBUG

public static boolean DEBUG
if true then debug info can be written


baseURI

public static java.lang.String baseURI
URI reference to the LatLong data baseURI/country/CCC/CCC_0_MAP.xml


baseFolder

public static java.lang.String baseFolder
Hardcoded File reference to the above URI Needed becasue we don;t know how to convert a URI to a file path


commonborderFolder

public static java.lang.String commonborderFolder
Hardcoded File reference to the commonborder property files. Needed becasue we don;t know how to convert a URI to a file path


problems

public static java.lang.StringBuffer problems
Used to build an error message for neighbors with no commonborder


bboxCheckOnly

public static boolean bboxCheckOnly
if true then only check for neighbors using BBox check This is used for generating the ZZZ world list.

Constructor Detail

NeighborUtility

public NeighborUtility()
Method Detail

doAllBorders

public static boolean doAllBorders(PlatformLatLongDataProvider fixture,
                                   java.util.List<java.lang.String[]> worldList)
This will generate a list of neighbors for all neighboring countries. It uses an array list (from DoWorld) as the source of neighbor countries.

Parameters:
fixture - needed to get the LatLong data
worldList - List of neighboring admin0 areas
Returns:
true

getAdmin

public static java.lang.String getAdmin(java.lang.String admin0)
Get the file name for the most detailed admin area for the specified admin 0

Parameters:
admin0 -
Returns:
file name for the admin area (i.e. USA_2_MAP.xml)

getAdmin0

public static java.lang.String getAdmin0(java.lang.String admin0)
Get the file name for the admin0 file (or admin1 if admin0 does not exist)

Parameters:
admin0 -
Returns:
file name for the admin area (i.e. USA_0_MAP.xml)

setArea

public static void setArea(java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map,
                           java.lang.String id,
                           LatLong latLong)
Called to input another LatLong object This builds a Map of latlong areas for an admin area

Parameters:
map - HashMap of ID to BoundaryBox for polygon
id - Admin area id
latLong - Latitude/longitude info

processAreas

public static java.util.List<java.lang.String[]> processAreas(java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map)
After all the latLong data has been submitted this method is called to generate the list of internal neighbors from this Map of AdminAreas. BBox1 is adjacent to BBox2 if any of the corners of BBox1 is contained in BBox2 or any corner of BBox2 is contained in BBox1

Parameters:
map - Map of AdminArea rectangles keyed by admin area
Returns:
List of neighbors.

matchArea

public static java.util.List<java.lang.String[]> matchArea(java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map1,
                                                           java.util.Map<java.lang.String,NeighborUtility.AdminArea[]> map2)
After all the latLong data has been submitted this method is called to generate the list of neighbors between the first set of Admin areas and the 2nd

Parameters:
map1 - Map of AdminArea rectangles keyed by admin area
map2 - Map of AdminArea rectangles keyed by admin area
Returns:
List of neighbors.

testAdjacency

public static boolean testAdjacency(NeighborUtility.AdminArea bbox1,
                                    NeighborUtility.AdminArea bbox2)
Test adjacency by containment of any corner of two bounding boxes If any corner of AdminArea 1 is contained in AdminArea 2 or any corner of AdminArea 2 is contained in AdminArea 1 then they are adjacent.

Parameters:
bbox1 - bounding box 1
bbox2 - bounding box 2
Returns:
true if adjacent or containment true

testAdjacencyMatch

public static boolean testAdjacencyMatch(NeighborUtility.AdminArea area1,
                                         NeighborUtility.AdminArea area2)
Test adjacency by matching the points on the border of each area for a match

Parameters:
area1 - AdminArea class containing polygon1
area2 - AdminArea class containing polygon2
Returns:
true if adjacent or containment true

closeTo

public static boolean closeTo(double lt1,
                              double ln1,
                              double lt2,
                              double ln2)
Check if point1 is close to point 2 by the amount of the delta. A delta of 0.01 is approx 1.11 km

Parameters:
lt1 - Point 1 latitude
ln1 - Point 1 longitude
lt2 - point 2 latitude
ln2 - point 2 longitude
Returns:
true if within delta.

testAdjacencyContains

public static boolean testAdjacencyContains(NeighborUtility.AdminArea bbox1,
                                            NeighborUtility.AdminArea bbox2)
Test adjacency by checking if any point on the border of one area is contained in the polygon for the other area

Parameters:
bbox1 - AdminArea class containing polygon1
bbox2 - AdminArea class containing polygon2
Returns:
true if adjacent or containment true

getPropertyFolder

public static java.lang.String getPropertyFolder()
get the folder to use for output.

Returns:
Fully qualified path (e.g. c:/tmp/commonborder)

statistics

public static void statistics()
print the statistics


debug

public static void debug(java.lang.String msg)
print debug messages to the r log.

Parameters:
msg -

output

public static void output(java.lang.String msg)
print messages to the log.

Parameters:
msg -

debug

public static void debug(java.lang.String msg,
                         java.lang.Throwable e)
debug output for exceptions

Parameters:
msg -
e -