Package com.maxmind.geoip2

Class DatabaseReader

  • All Implemented Interfaces:
    DatabaseProvider, GeoIp2Provider, Closeable, AutoCloseable
    public class DatabaseReader
extends Object
implements DatabaseProvider, Closeable

    The class DatabaseReader provides a reader for the GeoIP2 database format.

    Usage

    To use the database API, you must create a new DatabaseReader using the DatabaseReader.Builder. You must provide the Builder constructor either an InputStream or File for your GeoIP2 database. You may also specify the fileMode and the locales fallback order using the methods on the Builder object.

    After you have created the DatabaseReader, you may then call one of the appropriate methods, e.g., city or tryCity, for your database. These methods take the IP address to be looked up. The methods with the "try" prefix return an Optional object, which will be empty if the value is not present in the database. The method without the prefix will throw an AddressNotFoundException if the address is not in the database. If you are looking up many IPs that are not contained in the database, the "try" method will be slightly faster as they do not need to construct and throw an exception. These methods otherwise behave the same.

    If the lookup succeeds, the method call will return a response class for the GeoIP2 lookup. The class in turn contains multiple record classes, each of which represents part of the data returned by the database.

    We recommend reusing the DatabaseReader object rather than creating a new one for each lookup. The creation of this object is relatively expensive as it must read in metadata for the file. It is safe to share the object across threads.

    Caching

    The database API supports pluggable caching (by default, no caching is performed). A simple implementation is provided by com.maxmind.db.CHMCache. Using this cache, lookup performance is significantly improved at the cost of a small (~2MB) memory overhead.