java.lang.Object
com.maxmind.geoip2.DatabaseReader
All Implemented Interfaces:
Closeable, AutoCloseable
public class DatabaseReaderextends Object implements Closeable
Modified and simplified for I2P

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 the appropriate method (e.g., city) for your database, passing it the IP address you want to look up.

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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    DatabaseReader.Builder
    Constructs a Builder for the DatabaseReader.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final List<String>
    locales
    Languages to prefer in the results.
    private final Reader
    reader
    The open database file.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    DatabaseReader(DatabaseReader.Builder builder)
    Opens the database the builder describes.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the database.
    String
    country(String ipAddress)
    Looks up the two-letter ISO country code recorded for an address.
    void
    countryToIP(String country, Writer out)
    I2P - Write all IPv4 address ranges for the given country to out.
    private Object
    get(InetAddress ipAddress, String type)
    Returns a map containing: continent: Map containing: code: String names: Map of lang to translated name geoname_id: Long country: Map containing: iso_code: String names: Map of lang to translated name geoname_id: Long registered_country: Map containing: iso_code: String names: Map of lang to translated name geoname_id: Long
    Metadata
    getMetadata()
    Get the metadata recorded in the database, including its build epoch and the node count of the search tree.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • reader

      private final Reader reader
      The open database file.

    • locales

      private final List<String> locales
      Languages to prefer in the results.

  • Constructor Details

    • DatabaseReader

      private DatabaseReader(DatabaseReader.Builder builder) throws IOException
      Opens the database the builder describes.
      Parameters:
      builder - the builder describing where the database is
      Throws:
      IOException - if the database cannot be read

  • Method Details

    • get

      private Object get(InetAddress ipAddress, String type) throws IOException
      Returns a map containing:
      • continent: Map containing:
        • code: String
        • names: Map of lang to translated name
        • geoname_id: Long
        • country: Map containing:
          • iso_code: String
          • names: Map of lang to translated name
          • geoname_id: Long
          • registered_country: Map containing:
            • iso_code: String
            • names: Map of lang to translated name
            • geoname_id: Long
      Parameters:
      ipAddress - IPv4 or IPv6 address to lookup.
      type - the database type required, e.g. city or country
      Returns:
      A Map with the data for the IP address
      Throws:
      IOException - if there is an error opening or reading from the file.

    • close

      public void close() throws IOException

      Closes the database.

      If you are using FileMode.MEMORY_MAPPED, this will not unmap the underlying file due to a limitation in Java's MappedByteBuffer. It will however set the reference to the buffer to null, allowing the garbage collector to collect it.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if an I/O error occurs.

    • country

      public String country(String ipAddress) throws IOException
      Looks up the two-letter ISO country code recorded for an address.
      Parameters:
      ipAddress - IPv4 or IPv6 address
      Returns:
      the two-letter ISO country code, or null if the address has no country record
      Throws:
      IOException - if the address cannot be resolved or the database cannot be read

    • countryToIP

      public void countryToIP(String country, Writer out) throws IOException
      I2P - Write all IPv4 address ranges for the given country to out.
      Parameters:
      country - ISO 3166-1 alpha-2 code, matched case-insensitively here and upper-cased before the lookup
      out - caller must close
      Throws:
      IOException - if the database cannot be read or the write to out fails

    • getMetadata

      public Metadata getMetadata()
      Get the metadata recorded in the database, including its build epoch and the node count of the search tree.
      Returns:
      the metadata for the open MaxMind DB file.