{"id":18318541,"url":"https://github.com/maxmind/maxmind-db-reader-java","last_synced_at":"2025-04-13T04:00:00.810Z","repository":{"id":8723014,"uuid":"10394615","full_name":"maxmind/MaxMind-DB-Reader-java","owner":"maxmind","description":"Java reader for the MaxMind DB format","archived":false,"fork":false,"pushed_at":"2025-04-11T20:28:22.000Z","size":1429,"stargazers_count":122,"open_issues_count":2,"forks_count":44,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-04-13T03:59:55.735Z","etag":null,"topics":["geoip","geoip2","maxmind","mmdb"],"latest_commit_sha":null,"homepage":"https://maxmind.github.io/MaxMind-DB-Reader-java/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxmind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-05-31T00:05:16.000Z","updated_at":"2025-04-11T20:28:25.000Z","dependencies_parsed_at":"2023-01-14T11:49:21.073Z","dependency_job_id":"b9903bd7-523d-4d45-ae51-11cedb66afeb","html_url":"https://github.com/maxmind/MaxMind-DB-Reader-java","commit_stats":null,"previous_names":["maxmind/maxmind-db-java"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxmind","download_url":"https://codeload.github.com/maxmind/MaxMind-DB-Reader-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248661706,"owners_count":21141450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geoip","geoip2","maxmind","mmdb"],"created_at":"2024-11-05T18:09:57.847Z","updated_at":"2025-04-13T04:00:00.783Z","avatar_url":"https://github.com/maxmind.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaxMind DB Reader #\n\n## Description ##\n\nThis is the Java API for reading MaxMind DB files. MaxMind DB is a binary file\nformat that stores data indexed by IP address subnets (IPv4 or IPv6).\n\n## Installation ##\n\n### Maven ###\n\nWe recommend installing this package with [Maven](https://maven.apache.org/).\nTo do this, add the dependency to your pom.xml:\n\n```xml\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.maxmind.db\u003c/groupId\u003e\n        \u003cartifactId\u003emaxmind-db\u003c/artifactId\u003e\n        \u003cversion\u003e3.1.1\u003c/version\u003e\n    \u003c/dependency\u003e\n```\n\n### Gradle ###\n\nAdd the following to your `build.gradle` file:\n\n```\nrepositories {\n    mavenCentral()\n}\ndependencies {\n    compile 'com.maxmind.db:maxmind-db:3.1.1'\n}\n```\n\n## Usage ##\n\n*Note:* For accessing MaxMind GeoIP2 databases, we generally recommend using\nthe [GeoIP2 Java API](https://maxmind.github.io/GeoIP2-java/) rather than using\nthis package directly.\n\nTo use the API, you must first create a `Reader` object. The constructor for\nthe reader object takes a `File` representing your MaxMind DB. Optionally you\nmay pass a second parameter with a `FileMode` with a value of `MEMORY_MAP` or\n`MEMORY`. The default mode is `MEMORY_MAP`, which maps the file to virtual\nmemory. This often provides performance comparable to loading the file into\nreal memory with `MEMORY`.\n\nTo look up an IP address, pass the address as an `InetAddress` to the `get`\nmethod on `Reader`, along with the class of the object you want to\ndeserialize into. This method will create an instance of the class and\npopulate it. See examples below.\n\nWe recommend reusing the `Reader` object rather than creating a new one for\neach lookup. The creation of this object is relatively expensive as it must\nread in metadata for the file.\n\n## Example ##\n\n```java\nimport com.maxmind.db.MaxMindDbConstructor;\nimport com.maxmind.db.MaxMindDbParameter;\nimport com.maxmind.db.Reader;\nimport com.maxmind.db.DatabaseRecord;\n\nimport java.io.File;\nimport java.io.IOException;\nimport java.net.InetAddress;\n\npublic class Lookup {\n    public static void main(String[] args) throws IOException {\n        File database = new File(\"/path/to/database/GeoIP2-City.mmdb\");\n        try (Reader reader = new Reader(database)) {\n            InetAddress address = InetAddress.getByName(\"24.24.24.24\");\n\n            // get() returns just the data for the associated record\n            LookupResult result = reader.get(address, LookupResult.class);\n\n            System.out.println(result.getCountry().getIsoCode());\n\n            // getRecord() returns a DatabaseRecord class that contains both\n            // the data for the record and associated metadata.\n            DatabaseRecord\u003cLookupResult\u003e record\n                = reader.getRecord(address, LookupResult.class);\n\n            System.out.println(record.getData().getCountry().getIsoCode());\n            System.out.println(record.getNetwork());\n        }\n    }\n\n    public static class LookupResult {\n        private final Country country;\n\n        @MaxMindDbConstructor\n        public LookupResult (\n            @MaxMindDbParameter(name=\"country\") Country country\n        ) {\n            this.country = country;\n        }\n\n        public Country getCountry() {\n            return this.country;\n        }\n    }\n\n    public static class Country {\n        private final String isoCode;\n\n        @MaxMindDbConstructor\n        public Country (\n            @MaxMindDbParameter(name=\"iso_code\") String isoCode\n        ) {\n            this.isoCode = isoCode;\n        }\n\n        public String getIsoCode() {\n            return this.isoCode;\n        }\n    }\n}\n```\n\nYou can also use the reader object to iterate over the database. \nThe `reader.networks()` and `reader.networksWithin()` methods can \nbe used for this purpose.\n\n```java\nReader reader = new Reader(file);\nNetworks networks = reader.networks(Map.class);\n\nwhile(networks.hasNext()) {\n    DatabaseRecord\u003cMap\u003cString, String\u003e\u003e iteration = networks.next();\n\n    // Get the data.\n    Map\u003cString, String\u003e data = iteration.getData();\n\n    // The IP Address\n    InetAddress ipAddress = InetAddress.getByName(data.get(\"ip\"));\n\n    // ...\n}\n```\n\n\n## Caching ##\n\nThe database API supports pluggable caching (by default, no caching is\nperformed). A simple implementation is provided by `com.maxmind.db.CHMCache`.\nUsing this cache, lookup performance is significantly improved at the cost of\na small (~2MB) memory overhead.\n\nUsage:\n\n```java\nReader reader = new Reader(database, new CHMCache());\n```\n\nPlease note that the cache will hold references to the objects created\nduring the lookup. If you mutate the objects, the mutated objects will be\nreturned from the cache on subsequent lookups.\n\n## Multi-Threaded Use ##\n\nThis API fully supports use in multi-threaded applications. In such\napplications, we suggest creating one `Reader` object and sharing that among\nthreads.\n\n## Common Problems ##\n\n### File Lock on Windows ###\n\nBy default, this API uses the `MEMORY_MAP` mode, which memory maps the file.\nOn Windows, this may create an exclusive lock on the file that prevents it\nfrom being renamed or deleted. Due to the implementation of memory mapping in\nJava, this lock will not be released when the `DatabaseReader` is closed; it\nwill only be released when the object and the `MappedByteBuffer` it uses are\ngarbage collected. Older JVM versions may also not release the lock on exit.\n\nTo work around this problem, use the `MEMORY` mode or try upgrading your JVM\nversion. You may also call `System.gc()` after dereferencing the\n`DatabaseReader` object to encourage the JVM to garbage collect sooner.\n\n### Packaging Database in a JAR ###\n\nIf you are packaging the database file as a resource in a JAR file using\nMaven, you must\n[disable binary file filtering](https://maven.apache.org/plugins/maven-resources-plugin/examples/binaries-filtering.html).\nFailure to do so will result in `InvalidDatabaseException` exceptions being\nthrown when querying the database.\n\n## Format ##\n\nThe MaxMind DB format is an open format for quickly mapping IP addresses to\nrecords. The\n[specification](https://github.com/maxmind/MaxMind-DB/blob/main/MaxMind-DB-spec.md)\nis available, as is our\n[Perl writer](https://github.com/maxmind/MaxMind-DB-Writer-perl) for the\nformat.\n\n## Bug Tracker ##\n\nPlease report all issues with this code using the [GitHub issue\ntracker](https://github.com/maxmind/MaxMind-DB-Reader-java/issues).\n\nIf you are having an issue with a MaxMind database or service that is not\nspecific to this reader, please [contact MaxMind support](https://www.maxmind.com/en/support).\n\n## Requirements  ##\n\nThis API requires Java 11 or greater.\n\n## Contributing ##\n\nPatches and pull requests are encouraged. Please include unit tests whenever\npossible.\n\n## Versioning ##\n\nThe MaxMind DB Reader API uses [Semantic Versioning](https://semver.org/).\n\n## Copyright and License ##\n\nThis software is Copyright (c) 2014-2022 by MaxMind, Inc.\n\nThis is free software, licensed under the Apache License, Version 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxmind%2Fmaxmind-db-reader-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxmind%2Fmaxmind-db-reader-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxmind%2Fmaxmind-db-reader-java/lists"}