Package edu.cnu.mdi.mapping.loader

Class ShapefileCityLoader

java.lang.Object
edu.cnu.mdi.mapping.loader.ShapefileCityLoader
All Implemented Interfaces:
ICityLoader
public final class ShapefileCityLoader extends Object implements ICityLoader
Loads GeoJsonCityLoader.CityFeature instances from an ESRI Shapefile set (.shp + .dbf) without any third-party dependencies.

Expected shapefile schema

The .dbf attribute table should contain the following fields (tried in priority order; the first non-empty value is used):

  • Name — NAME, name, NAMEASCII, NAME_EN — city display name.
  • Country — ADM0NAME, adm0name, SOV0NAME, COUNTRY — country name.
  • Population — POP_MAX, pop_max, POPULATION, POP2015 — population estimate as an integer string; -1 if absent or non-numeric.
  • Scalerank — SCALERANK, scalerank, SCALE_RANK — importance rank as an integer string; -1 if absent or non-numeric.

Features where the name field is absent or empty are silently skipped. Features with unknown population or scalerank are included but will report -1 for those values, which the renderers treat as "unknown".

Supported geometry types

Only ShapefileGeometryReader.TYPE_POINT and ShapefileGeometryReader.TYPE_MULTIPOINT records are used. City shapefiles (e.g. Natural Earth ne_10m_populated_places.shp) use Point geometry exclusively. For MultiPoint records, the first point in the set is used as the city location.

Coordinate assumptions

Input coordinates must be WGS84 or NAD83/GRS80 geographic degrees (longitude, latitude). NAD83 is treated as WGS84 without datum transformation. A companion .prj, when present, is validated and incompatible or unrecognized coordinate systems are rejected. If it is absent, WGS84 is assumed. Coordinates are converted to radians and longitude is wrapped to (-π, π] before being stored in the returned features.

File layout contract

The .dbf file is derived from the .shp path by replacing the extension. Both files must reside in the same directory with the same base name.

Usage


 ICityLoader loader = new ShapefileCityLoader();
 List<GeoJsonCityLoader.CityFeature> cities =
         loader.load(Path.of("/data/ne_10m_populated_places.shp"));
 mapView.setCities(cities);

This class is stateless and thread-safe; a single instance may be reused across multiple load(java.nio.file.Path) calls.

  • Constructor Details

    • ShapefileCityLoader

      public ShapefileCityLoader()

  • Method Details

    • load

      public List<GeoJsonCityLoader.CityFeature> load(Path path) throws IOException
      Loads city features from the given filesystem path.

      The path may point to the primary file of a multi-file format (e.g. the .shp file of a shapefile set) or to a self-contained file (e.g. a .geojson file). Implementations are responsible for locating companion files (e.g. .dbf, .shx) relative to the supplied path.

      Opens path as the .shp geometry file and derives the companion .dbf attribute path by replacing the file extension.

      Specified by:
      load in interface ICityLoader
      Parameters:
      path - path to the .shp file; the companion .dbf must exist in the same directory with the same base name
      Returns:
      unmodifiable list of city features; never null
      Throws:
      IOException - if either file cannot be opened or read

    • loadFromResource

      public List<GeoJsonCityLoader.CityFeature> loadFromResource(String resourcePath)
      Loads city features from a classpath resource.

      The resource path must be absolute (begin with /). For multi-file formats this may not be supportable; implementations should throw UnsupportedOperationException with a clear message in that case.

      Shapefiles are multi-file formats and cannot be loaded from a single classpath resource. This method always throws UnsupportedOperationException. Use load(Path) with a filesystem path instead.

      Specified by:
      loadFromResource in interface ICityLoader
      Parameters:
      resourcePath - absolute classpath resource path; must not be null
      Returns:
      unmodifiable list of city features; never null
      Throws:
      UnsupportedOperationException - always