Interface GeographyService

public interface GeographyService

Used to create, save, retrieve, update and delete Geographical entities from persistent storage The biz.janux.geography package strives to treat City/State/Province/Country as entities, rather than as mere strings within an address (though it also supports the string-based approach); by treating geographical subdivisions as entities, it becomes possible, for example, to store information about these geographical subdivisions, or to easily derive geography-based statistics.

This approach presents challenges at the implementation level, as it may not be possible, or practical, to pre-store every city in a single Country, or every state in every Country.

Thus, the implementing class must choose how it will deal with the different use cases that may arise in a specific application. The default implementation considers the following three use-cases, which should satisfy most situations:

  1. The city is entered through a free-form input box, and the State/Province and Country fields are selected via pre-populated drop-downs.
  2. The City, State/Province and Country fields are entered as free-form strings where the application has no control over the formatting of these strings (for example they are received from a third-party or legacy system via an integration channel)
  3. A combination of the two cases above.

The default implementation stores Postal Addresses in the following manner. If the Postal Address

Note that the default implementation includes a list of all Countries in the world and their ISO code, as well as all States in the United States, and all Provinces in Canada. Also, it contains a special 'UNKNOWN' State/Province for each Country when it is desireable to associate a City to a Country, without using a State/Province.

As a result of all the above, the default implementation has the following characteristics: