com.maxmind.geoip2

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 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 Classes

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

Method Summary

Modifier and Type	Method and 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.

Methods inherited from class java.lang.Object

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

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'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 Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if an I/O error occurs.

country

public CountryResponse country(InetAddress ipAddress)
                        throws IOException,
                               GeoIp2Exception

Specified by:

country in interface GeoIp2Provider

Parameters:

ipAddress - IPv4 or IPv6 address to lookup.

Returns:

A Country model for the requested IP address.

Throws:

IOException - if there is an IO error

GeoIp2Exception - if there is an error looking up the IP

tryCountry

public Optional<CountryResponse> tryCountry(InetAddress ipAddress)
                                     throws IOException,
                                            GeoIp2Exception

Specified by:

tryCountry in interface DatabaseProvider

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 error

GeoIp2Exception - if there is an error looking up the IP

city

public CityResponse city(InetAddress ipAddress)
                  throws IOException,
                         GeoIp2Exception

Specified by:

city in interface GeoIp2Provider

Parameters:

ipAddress - IPv4 or IPv6 address to lookup.

Returns:

A City model for the requested IP address.

Throws:

IOException - if there is an IO error

GeoIp2Exception - if there is an error looking up the IP

tryCity

public Optional<CityResponse> tryCity(InetAddress ipAddress)
                               throws IOException,
                                      GeoIp2Exception

Specified by:

tryCity in interface DatabaseProvider

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 error

GeoIp2Exception - 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 interface DatabaseProvider

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 IP

IOException - 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 interface DatabaseProvider

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 error

GeoIp2Exception - 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 interface DatabaseProvider

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 IP

IOException - 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 interface DatabaseProvider

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 error

GeoIp2Exception - 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 interface DatabaseProvider

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 IP

IOException - 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 interface DatabaseProvider

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 error

GeoIp2Exception - 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 interface DatabaseProvider

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 IP

IOException - 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 interface DatabaseProvider

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 error

GeoIp2Exception - 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 interface DatabaseProvider

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 IP

IOException - 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 interface DatabaseProvider

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 error

GeoIp2Exception - 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 interface DatabaseProvider

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 IP

IOException - 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 interface DatabaseProvider

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 error

GeoIp2Exception - if there is an error looking up the IP

getMetadata

public Metadata getMetadata()

Returns:

the metadata for the open MaxMind DB file.