Berico-Technologies/CLAVIN — pull request #105 by mrburrito (2014-12-12 20:22:24+00:00)
Title: Configurable ancestry resolution for Gazetteer queries and CLAVIN location resolution.

This pull request addresses #104, the performance hit in CLAVIN 2.0.0 due to the automatic loading of ancestry (the containing administrative districts) for all GeoNames returned by the Gazetteer lookup. This was resulting in 1-5 additional Lucene queries for every lookup, depending on the depth of the results returned. For any number of search results, `N`, the worst case scenario (all results have unique ancestry and have 4 admin districts and a country that contain them) would be 5 queries to load `5N` ancestors from the index. This resulted in a 2-3x decrease in performance.

The solution was to configure three different methods for loading the ancestry of a GeoName, `ON_CREATE`, `LAZY`, and `MANUAL`. `ON_CREATE` behaves the same as CLAVIN 2.0.0, loading the ancestry when Gazetteer queries are executed. `LAZY`, which is now the default for all queries unless otherwise specified, triggers a load of all a GeoName's ancestors when `getParent()` is first called. This eliminates the performance hit on query but allows simple retrieval of the ancestry if it is later required. Queries running in `MANUAL` mode do not load ancestry and users will have to call the new `Gazetteer.loadAncestry()` method with the returned GeoNames in order to access their ancestors.

I also bumped the version number to 2.0.1-SNAPSHOT since this is a fairly significant API change. Not sure if it warrants a bump to 2.1.0 or not. All APIs are backwards compatible to 2.0.0 with reasonable defaults, though behavior is changed to improve out-of-the-box performance.