Class DatabaseReader
- All Implemented Interfaces:
DatabaseProvider
,GeoIp2Provider
,Closeable
,AutoCloseable
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Constructs a Builder for theDatabaseReader
. -
Method Summary
Modifier and TypeMethodDescriptionanonymousIp
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Anonymous IP.asn
(InetAddress ipAddress) Look up an IP address in a GeoLite2 ASN database.city
(InetAddress ipAddress) void
close()
Closes the database.connectionType
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Connection Type database.country
(InetAddress ipAddress) domain
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Domain database.enterprise
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Enterprise database.isp
(InetAddress ipAddress) Look up an IP address in a GeoIP2 ISP database.tryAnonymousIp
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Anonymous IP.tryAsn
(InetAddress ipAddress) Look up an IP address in a GeoLite2 ASN database.tryCity
(InetAddress ipAddress) tryConnectionType
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Connection Type database.tryCountry
(InetAddress ipAddress) tryDomain
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Domain database.tryEnterprise
(InetAddress ipAddress) Look up an IP address in a GeoIP2 Enterprise database.tryIsp
(InetAddress ipAddress) Look up an IP address in a GeoIP2 ISP database.
-
Method Details
-
close
Closes the database.
If you are using
FileMode.MEMORY_MAPPED
, this will not unmap the underlying file due to a limitation in Java'sMappedByteBuffer
. It will however set the reference to the buffer tonull
, allowing the garbage collector to collect it.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- if an I/O error occurs.
-
country
- Specified by:
country
in interfaceGeoIp2Provider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A Country model for the requested IP address.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
tryCountry
public Optional<CountryResponse> tryCountry(InetAddress ipAddress) throws IOException, GeoIp2Exception - Specified by:
tryCountry
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A Country model for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
city
- Specified by:
city
in interfaceGeoIp2Provider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A City model for the requested IP address.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
tryCity
- Specified by:
tryCity
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- A City model for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
anonymousIp
Look up an IP address in a GeoIP2 Anonymous IP.- Specified by:
anonymousIp
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- a AnonymousIpResponse for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
tryAnonymousIp
public Optional<AnonymousIpResponse> tryAnonymousIp(InetAddress ipAddress) throws IOException, GeoIp2Exception Description copied from interface:DatabaseProvider
Look up an IP address in a GeoIP2 Anonymous IP.- Specified by:
tryAnonymousIp
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- a AnonymousIpResponse for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
asn
Look up an IP address in a GeoLite2 ASN database.- Specified by:
asn
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- an AsnResponse for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
tryAsn
Description copied from interface:DatabaseProvider
Look up an IP address in a GeoLite2 ASN database.- Specified by:
tryAsn
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- an IspResponse for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
connectionType
public ConnectionTypeResponse connectionType(InetAddress ipAddress) throws IOException, GeoIp2Exception Look up an IP address in a GeoIP2 Connection Type database.- Specified by:
connectionType
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- a ConnectTypeResponse for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
tryConnectionType
public Optional<ConnectionTypeResponse> tryConnectionType(InetAddress ipAddress) throws IOException, GeoIp2Exception Description copied from interface:DatabaseProvider
Look up an IP address in a GeoIP2 Connection Type database.- Specified by:
tryConnectionType
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- a ConnectTypeResponse for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
domain
Look up an IP address in a GeoIP2 Domain database.- Specified by:
domain
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- a DomainResponse for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
tryDomain
public Optional<DomainResponse> tryDomain(InetAddress ipAddress) throws IOException, GeoIp2Exception Description copied from interface:DatabaseProvider
Look up an IP address in a GeoIP2 Domain database.- Specified by:
tryDomain
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- a DomainResponse for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
enterprise
Look up an IP address in a GeoIP2 Enterprise database.- Specified by:
enterprise
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- an EnterpriseResponse for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
tryEnterprise
public Optional<EnterpriseResponse> tryEnterprise(InetAddress ipAddress) throws IOException, GeoIp2Exception Description copied from interface:DatabaseProvider
Look up an IP address in a GeoIP2 Enterprise database.- Specified by:
tryEnterprise
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- an EnterpriseResponse for the requested IP address or empty if the IP address is not in the DB.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
isp
Look up an IP address in a GeoIP2 ISP database.- Specified by:
isp
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup.- Returns:
- an IspResponse for the requested IP address.
- Throws:
GeoIp2Exception
- if there is an error looking up the IPIOException
- if there is an IO error
-
tryIsp
Description copied from interface:DatabaseProvider
Look up an IP address in a GeoIP2 ISP database.- Specified by:
tryIsp
in interfaceDatabaseProvider
- Parameters:
ipAddress
- IPv4 or IPv6 address to lookup or empty if the IP address is not in the DB.- Returns:
- an IspResponse for the requested IP address.
- Throws:
IOException
- if there is an IO errorGeoIp2Exception
- if there is an error looking up the IP
-
getMetadata
- Returns:
- the metadata for the open MaxMind DB file.
-