|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
The default implementation stores Postal Addresses in the following manner. If the Postal Address
contains a match to a City entity that exists in the database (application recognizes a city, State/Province, and Country combination) than the Postal Address is matched against the corresponding City entity (which contains references to its enclosing State/Province and Country)
contains a match to a State/Province entity that exists in the database (application recognizes State/Province and Country combination). In such a case, a new City entity is created with the name supplied, and the Postal Address will contain a reference to this City entity. This would be the Use Case, for example, when a User is entering an address using pre-populated Country and State/Province drop-downs, and a free-form City. Note that this is imperfect and may mean that two records may be created for the same city, if two different spellings are given for the City, e.g. New York vs. NewYork.
does not contain a match to a State/Province entity that exists in the database, than all fields in the Postal Address are stored using the strings contained in the PostalAddress instance, and no attempt is made to create City or State/Province entities. This would be the Use Case where the City, State/Province and Country are entered via free-form strings and it is not possible or desirable to match these to pre-existing entities.
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:
This default implementation, while making a step in the direction of relating Postal Adresses to Geographical Entities (City, State/Province, Country), still leaves the possibility open of there being duplicate cities with different spellings. An improvement of this default implementation would be to ask the User to disambiguate close spellings. For example, if the User enters 'NewYork', a dialog box would display that says "did you mean 'New York' ?" and provides a list of closely spelled alternatives. An approximate match algorythm could be used to implement such a flow. An other alternative would be to integrate with a third-party geographic service, such as ESRI or google maps.
Method Summary | |
---|---|
City |
findCityByName(StateProvince state,
String cityName)
retrieves a City within a country and state by performing a cap-insensitive search by name, or returns null if a City
with that name is not found |
City |
findCityByName(String countryCode,
String stateCode,
String cityName)
retrieves a City within a country and state by performing a cap-insensitive search by name, and using the ISO country code and a state code, or returns null if a City with that name is not found |
Country |
findCountryByCode(String code)
retrieves a Country using a standard ISO code, or returns null if a Country with that code is not found |
Country |
findCountryByName(String name)
retrieves a Country by performing a cap-insensitive search by name, or returns null if a Country with that name is not found |
StateProvince |
findStateByCode(String countryCode,
String stateCode)
retrieves a State using a country code and state code, where the country code is a standard ISO code, or returns null if a State with
those codes is not found |
StateProvince |
findStateByName(String countryCode,
String stateName)
retrieves a State by performing a cap-insensitive search by name, within a country with the specified ISO country code, or returns null if a
State with that name is not found |
Map |
findStatesByCountry(String countryCode)
loads all the State/Provinces that exist within a Country in the system |
Map |
loadAllCountries()
Returns a map of all Countries in the system, keyed by ISO code; the keys of the map may be ordered by the implementation (for example according to Country.getSortOrder()) |
Country |
loadCountry(Integer id)
loads a Country object from persistence using its id |
StateProvince |
loadUnknownState(String countryCode)
loads the State object used to link City and Country in the event that the specific StateProvince to which the City belongs has not been defined |
City |
newCity(StateProvince state,
String cityName)
instantiates a new City within the specified StateProvince, with the name provided |
void |
saveCity(City city)
adds a city to the system |
void |
setCityStateCountry(PostalAddress aPostalAddress)
Checks to see whether the PostalAddress provided is associated with Geographic Entities (City, StateProvince and/or Country), based on the contents of the PostalAddress AsString fields |
Method Detail |
---|
Country loadCountry(Integer id) throws EntityNotFoundException
id
- the internal identifier of the Country
EntityNotFoundException
- if a Country object with that id is not foundMap loadAllCountries()
Country findCountryByCode(String code)
null
if a Country with that code is not found
code
- the two-letter ISO country codeCountry findCountryByName(String name)
null
if a Country with that name is not found
name
- the name in the default system languageStateProvince findStateByCode(String countryCode, String stateCode)
null
if a State with
those codes is not found
countryCode
- a two-letter ISO country codestateCode
- a country-specific state abbreviation codeStateProvince findStateByName(String countryCode, String stateName)
null
if a
State with that name is not found
countryCode
- a two-letter ISO country codestateName
- the name of a state in the default system languageStateProvince loadUnknownState(String countryCode)
countryCode
- the two-letter ISO code for a country
IllegalStateException
- if an 'Unknown' StateProvince has not been
created for that Country in the systemMap findStatesByCountry(String countryCode)
countryCode
- the two-letter ISO code for a countryCity findCityByName(StateProvince state, String cityName)
null
if a City
with that name is not found
state
- a StateProvince that has been persisted in the systemcityName
- the name of a city in the default system languageCity findCityByName(String countryCode, String stateCode, String cityName)
null
if a City with that name is not found
countryCode
- a two-letter ISO country codestateCode
- a country-specific state abbreviation codecityName
- the name of a city in the default system languageCity newCity(StateProvince state, String cityName)
state
- a name that has been persisted in the systemcityName
- the name for the new system, in the default system
languagevoid saveCity(City city)
void setCityStateCountry(PostalAddress aPostalAddress)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |