java.lang.Object
com.maxmind.db.Reader
All Implemented Interfaces:
Closeable, AutoCloseable
public final class Readerextends Object implements Closeable
Instances of this class provide a reader for the MaxMind DB format. IP addresses can be looked up using the get method.

  • Field Details

    • DATA_SECTION_SEPARATOR_SIZE

      private static final int DATA_SECTION_SEPARATOR_SIZE
      Size of the separator before the data section, in bytes.
      See Also:

    • METADATA_START_MARKER

      private static final byte[] METADATA_START_MARKER
      Marker preceding the database metadata.

    • ipV4Start

      private final int ipV4Start
      Index of the IPv4 subtree's start node.

    • metadata

      private final Metadata metadata
      Metadata read from the database.

    • bufferHolderReference

      private final AtomicReference<BufferHolder> bufferHolderReference
      Holder for the database data, for reloads.

    • cache

      private final NodeCache cache
      Cache of the tree nodes read.

  • Constructor Details

    • Reader

      public Reader(File database) throws IOException
      Constructs a Reader for the MaxMind DB format, with no caching. The file passed to it must be a valid MaxMind DB file such as a GeoIP2 database file.
      Parameters:
      database - the MaxMind DB file to use.
      Throws:
      IOException - if there is an error opening or reading from the file.

    • Reader

      public Reader(File database, NodeCache cache) throws IOException
      Constructs a Reader for the MaxMind DB format, with the specified backing cache. The file passed to it must be a valid MaxMind DB file such as a GeoIP2 database file.
      Parameters:
      database - the MaxMind DB file to use.
      cache - backing cache instance
      Throws:
      IOException - if there is an error opening or reading from the file.

    • Reader

      public Reader(InputStream source) throws IOException
      Constructs a Reader with no caching, as if in mode Reader.FileMode.MEMORY, without using a File instance.
      Parameters:
      source - the InputStream that contains the MaxMind DB file.
      Throws:
      IOException - if there is an error reading from the Stream.

    • Reader

      public Reader(InputStream source, NodeCache cache) throws IOException
      Constructs a Reader with the specified backing cache, as if in mode Reader.FileMode.MEMORY, without using a File instance.
      Parameters:
      source - the InputStream that contains the MaxMind DB file.
      cache - backing cache instance
      Throws:
      IOException - if there is an error reading from the Stream.

    • Reader

      public Reader(File database, Reader.FileMode fileMode) throws IOException
      Constructs a Reader for the MaxMind DB format, with no caching. The file passed to it must be a valid MaxMind DB file such as a GeoIP2 database file.
      Parameters:
      database - the MaxMind DB file to use.
      fileMode - the mode to open the file with.
      Throws:
      IOException - if there is an error opening or reading from the file.

    • Reader

      public Reader(File database, Reader.FileMode fileMode, NodeCache cache) throws IOException
      Constructs a Reader for the MaxMind DB format, with the specified backing cache. The file passed to it must be a valid MaxMind DB file such as a GeoIP2 database file.
      Parameters:
      database - the MaxMind DB file to use.
      fileMode - the mode to open the file with.
      cache - backing cache instance
      Throws:
      IOException - if there is an error opening or reading from the file.

    • Reader

      private Reader(BufferHolder bufferHolder, String name, NodeCache cache) throws IOException
      Opens a reader on an already loaded database.
      Parameters:
      bufferHolder - the holder for the database data
      name - the database name for the error messages
      cache - the node cache to use
      Throws:
      IOException - if the metadata cannot be read

  • Method Details

    • get

      public Object get(InetAddress ipAddress) throws IOException
      Looks up the address in the MaxMind DB.
      Parameters:
      ipAddress - the IP address to look up.
      Returns:
      the record for the IP address.
      Throws:
      IOException - if a file I/O error occurs.

    • countryToIP

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

    • getBufferHolder

      private BufferHolder getBufferHolder() throws ClosedDatabaseException
      Returns the holder for the database data.
      Returns:
      the current holder
      Throws:
      ClosedDatabaseException - if the database is closed

    • findAddressInTree

      private int findAddressInTree(ByteBuffer buffer, InetAddress address) throws InvalidDatabaseException
      Finds the node or data pointer for an address.
      Parameters:
      buffer - the buffer holding the database data
      address - the address to locate
      Returns:
      the record number, or -1 if not found
      Throws:
      InvalidDatabaseException - if the tree is corrupt

    • startNode

      private int startNode(int bitLength)
      Returns the first node to search for an address family.
      Parameters:
      bitLength - the address family size, in bits
      Returns:
      the start node number

    • findIpV4StartNode

      private int findIpV4StartNode(ByteBuffer buffer) throws InvalidDatabaseException
      Finds the start node of the IPv4 subtree.
      Parameters:
      buffer - the buffer holding the database data
      Returns:
      the start node number, 0 if the tree is smaller
      Throws:
      InvalidDatabaseException - if the tree is corrupt

    • readNode

      private int readNode(ByteBuffer buffer, int nodeNumber, int index) throws InvalidDatabaseException
      Reads one node from the tree.
      Parameters:
      buffer - the buffer holding the database data
      nodeNumber - the node to read
      index - the index of the node's data
      Returns:
      the node value
      Throws:
      InvalidDatabaseException - if the tree is corrupt

    • resolveDataPointer

      private Object resolveDataPointer(ByteBuffer buffer, int pointer) throws IOException
      Resolves a data pointer to its value.
      Parameters:
      buffer - the buffer holding the database data
      pointer - the pointer to resolve
      Returns:
      the decoded value
      Throws:
      IOException - if the data cannot be read

    • findMetadataStart

      private int findMetadataStart(ByteBuffer buffer, String databaseName) throws InvalidDatabaseException
      Finds the start of the database metadata in the buffer.
      Parameters:
      buffer - the buffer holding the database data
      databaseName - the database name for the error message
      Returns:
      the metadata offset
      Throws:
      InvalidDatabaseException - if the marker is missing

    • getMetadata

      public Metadata getMetadata()
      Returns the metadata for the MaxMind DB file.
      Returns:
      the metadata for the MaxMind DB 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.