Class DatabaseReader
- java.lang.Object
-
- com.maxmind.geoip2.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 theDatabaseReader.Builder
. You must provide theBuilder
constructor either anInputStream
orFile
for your GeoIP2 database. You may also specify thefileMode
and thelocales
fallback order using the methods on theBuilder
object.After you have created the
DatabaseReader
, you may then call one of the appropriate methods, e.g.,city
ortryCity
, for your database. These methods take the IP address to be looked up. The methods with the "try" prefix return anOptional
object, which will be empty if the value is not present in the database. The method without the prefix will throw anAddressNotFoundException
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 Classes Modifier and Type Class Description static class
DatabaseReader.Builder
Constructs a Builder for theDatabaseReader
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description AnonymousIpResponse
anonymousIp(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Anonymous IP.AsnResponse
asn(InetAddress ipAddress)
Look up an IP address in a GeoLite2 ASN database.CityResponse
city(InetAddress ipAddress)
void
close()
Closes the database.ConnectionTypeResponse
connectionType(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Connection Type database.CountryResponse
country(InetAddress ipAddress)
DomainResponse
domain(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Domain database.EnterpriseResponse
enterprise(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Enterprise database.Metadata
getMetadata()
IspResponse
isp(InetAddress ipAddress)
Look up an IP address in a GeoIP2 ISP database.Optional<AnonymousIpResponse>
tryAnonymousIp(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Anonymous IP.Optional<AsnResponse>
tryAsn(InetAddress ipAddress)
Look up an IP address in a GeoLite2 ASN database.Optional<CityResponse>
tryCity(InetAddress ipAddress)
Optional<ConnectionTypeResponse>
tryConnectionType(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Connection Type database.Optional<CountryResponse>
tryCountry(InetAddress ipAddress)
Optional<DomainResponse>
tryDomain(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Domain database.Optional<EnterpriseResponse>
tryEnterprise(InetAddress ipAddress)
Look up an IP address in a GeoIP2 Enterprise database.Optional<IspResponse>
tryIsp(InetAddress ipAddress)
Look up an IP address in a GeoIP2 ISP database.
-
-
-
Method Detail
-
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'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
public CountryResponse country(InetAddress ipAddress) throws IOException, GeoIp2Exception
- 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
public CityResponse city(InetAddress ipAddress) throws IOException, GeoIp2Exception
- 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
public Optional<CityResponse> tryCity(InetAddress ipAddress) throws IOException, GeoIp2Exception
- 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
public AnonymousIpResponse anonymousIp(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public AsnResponse asn(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public Optional<AsnResponse> tryAsn(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public DomainResponse domain(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public EnterpriseResponse enterprise(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public IspResponse isp(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public Optional<IspResponse> tryIsp(InetAddress ipAddress) throws IOException, GeoIp2Exception
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
public Metadata getMetadata()
- Returns:
- the metadata for the open MaxMind DB file.
-
-