Merge pull request #82 from maxmind/development

Merge development branch that drops dependency on jackson-databind

Author: oschwald

CHANGELOG.md

@@ -1,6 +1,17 @@
 CHANGELOG
 =========
 
+2.0.0
+------------------
+* Significant API changes. The `get()` and `getRecord()` methods now take a
+  class parameter specifying the type of object to deserialize into. You
+  can either deserialize into a `Map` or to model classes that use the
+  `MaxMindDbConstructor` and `MaxMindDbParameter` annotations to identify
+  the constructors and parameters to deserialize into.
+* `jackson-databind` is no longer a dependency.
+* The `Record` class is now named `DatabaseRecord`. This is to avoid a
+  conflict with `java.lang.Record` in Java 14.
+
 1.4.0 (2020-06-12)
 ------------------
 

README.md

@@ -10,7 +10,7 @@ format that stores data indexed by IP address subnets (IPv4 or IPv6).
 
 ### Maven ###
 
-We recommend installing this package with [Maven](http://maven.apache.org/).
+We recommend installing this package with [Maven](https://maven.apache.org/).
 To do this, add the dependency to your pom.xml:
 
 ```xml
@@ -37,7 +37,7 @@ dependencies {
 ## Usage ##
 
 *Note:* For accessing MaxMind GeoIP2 databases, we generally recommend using
-the [GeoIP2 Java API](http://maxmind.github.io/GeoIP2-java/) rather than using
+the [GeoIP2 Java API](https://maxmind.github.io/GeoIP2-java/) rather than using
 this package directly.
 
 To use the API, you must first create a `Reader` object. The constructor for
@@ -48,11 +48,9 @@ memory. This often provides performance comparable to loading the file into
 real memory with `MEMORY`.
 
 To look up an IP address, pass the address as an `InetAddress` to the `get`
-method on `Reader`. This method will return the result as a
-`com.fasterxml.jackson.databind.JsonNode` object. `JsonNode` objects are used
-as they provide a convenient representation of multi-type data structures and
-the databind package of Jackson 2 supplies many tools for interacting with the
-data in this format.
+method on `Reader`, along with the class of the object you want to
+deserialize into. This method will create an instance of the class and
+populate it. See examples below.
 
 We recommend reusing the `Reader` object rather than creating a new one for
 each lookup. The creation of this object is relatively expensive as it must
@@ -61,7 +59,8 @@ read in metadata for the file.
 ## Example ##
 
 ```java
-import com.fasterxml.jackson.databind.JsonNode;
+import com.maxmind.db.MaxMindDbConstructor;
+import com.maxmind.db.MaxMindDbParameter;
 import com.maxmind.db.Reader;
 import com.maxmind.db.Record;
 
@@ -73,26 +72,56 @@ public class Lookup {
     public static void main(String[] args) throws IOException {
         File database = new File("/path/to/database/GeoIP2-City.mmdb");
         try (Reader reader = new Reader(database)) {
-
             InetAddress address = InetAddress.getByName("24.24.24.24");
 
             // get() returns just the data for the associated record
-            JsonNode recordData = reader.get(address);
+            LookupResult result = reader.get(address, LookupResult.class);
 
-            System.out.println(recordData);
+            System.out.println(result.getCountry().getIsoCode());
 
             // getRecord() returns a Record class that contains both
             // the data for the record and associated metadata.
-            Record record = reader.getRecord(address);
+            Record<LookupResult> record
+                = reader.getRecord(address, LookupResult.class);
 
-            System.out.println(record.getData());
+            System.out.println(record.getData().getCountry().getIsoCode());
             System.out.println(record.getNetwork());
         }
     }
+
+    public static class LookupResult {
+        private final Country country;
+
+        @MaxMindDbConstructor
+        public LookupResult (
+            @MaxMindDbParameter(name="country") Country country
+        ) {
+            this.country = country;
+        }
+
+        public Country getCountry() {
+            return this.country;
+        }
+    }
+
+    public static class Country {
+        private final String isoCode;
+
+        @MaxMindDbConstructor
+        public Country (
+            @MaxMindDbParameter(name="iso_code") String isoCode
+        ) {
+            this.isoCode = isoCode;
+        }
+
+        public String getIsoCode() {
+            return this.isoCode;
+        }
+    }
 }
 ```
 
-### Caching ###
+## Caching ##
 
 The database API supports pluggable caching (by default, no caching is
 performed). A simple implementation is provided by `com.maxmind.db.CHMCache`.
@@ -105,6 +134,10 @@ Usage:
 Reader reader = new Reader(database, new CHMCache());
 ```
 
+Please note that the cache will hold references to the objects created
+during the lookup. If you mutate the objects, the mutated objects will be
+returned from the cache on subsequent lookups.
+
 ## Multi-Threaded Use ##
 
 This API fully supports use in multi-threaded applications. In such
@@ -130,7 +163,7 @@ version. You may also call `System.gc()` after dereferencing the
 
 If you are packaging the database file as a resource in a JAR file using
 Maven, you must
-[disable binary file filtering](http://maven.apache.org/plugins/maven-resources-plugin/examples/binaries-filtering.html).
+[disable binary file filtering](https://maven.apache.org/plugins/maven-resources-plugin/examples/binaries-filtering.html).
 Failure to do so will result in `InvalidDatabaseException` exceptions being
 thrown when querying the database.
 
@@ -139,18 +172,18 @@ thrown when querying the database.
 The MaxMind DB format is an open format for quickly mapping IP addresses to
 records. The
 [specification](https://github.com/maxmind/MaxMind-DB/blob/master/MaxMind-DB-spec.md)
-is available as part of our
+is available, as is our
 [Perl writer](https://github.com/maxmind/MaxMind-DB-Writer-perl) for the
 format.
 
 ## Bug Tracker ##
 
-Please report all issues with this code using the [GitHub issue tracker]
-(https://github.com/maxmind/MaxMind-DB-Reader-java/issues).
+Please report all issues with this code using the [GitHub issue
+tracker](https://github.com/maxmind/MaxMind-DB-Reader-java/issues).
 
 If you are having an issue with a MaxMind database or service that is not
 specific to this reader, please [contact MaxMind support]
-(http://www.maxmind.com/en/support).
+(https://www.maxmind.com/en/support).
 
 ## Requirements  ##
 
@@ -163,7 +196,7 @@ possible.
 
 ## Versioning ##
 
-The MaxMind DB Reader API uses [Semantic Versioning](http://semver.org/).
+The MaxMind DB Reader API uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License ##
 

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.maxmind.db</groupId>
     <artifactId>maxmind-db</artifactId>
-    <version>1.4.1-SNAPSHOT</version>
+    <version>2.0.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <name>MaxMind DB Reader</name>
     <description>Reader for MaxMind DB</description>
@@ -42,11 +42,6 @@
             <version>4.13</version>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>com.fasterxml.jackson.core</groupId>
-            <artifactId>jackson-databind</artifactId>
-            <version>2.11.0</version>
-        </dependency>
     </dependencies>
     <build>
         <plugins>

sample/Benchmark.java

@@ -1,9 +1,9 @@
 import java.io.File;
 import java.io.IOException;
 import java.net.InetAddress;
+import java.util.Map;
 import java.util.Random;
 
-import com.fasterxml.jackson.databind.JsonNode;
 import com.maxmind.db.CHMCache;
 import com.maxmind.db.InvalidDatabaseException;
 import com.maxmind.db.NoCache;
@@ -45,7 +45,7 @@ private static void bench(Reader r, int count, int seed) throws IOException {
         for (int i = 0; i < count; i++) {
             random.nextBytes(address);
             InetAddress ip = InetAddress.getByAddress(address);
-            JsonNode t = r.get(ip);
+            Map t = r.get(ip, Map.class);
             if (TRACE) {
                 if (i % 50000 == 0) {
                     System.out.println(i + " " + ip);

src/main/java/com/maxmind/db/CHMCache.java

@@ -3,8 +3,6 @@
 import java.io.IOException;
 import java.util.concurrent.ConcurrentHashMap;
 
-import com.fasterxml.jackson.databind.JsonNode;
-
 /**
  * A simplistic cache using a {@link ConcurrentHashMap}. There's no eviction
  * policy, it just fills up until reaching the specified capacity <small>(or
@@ -15,7 +13,7 @@ public class CHMCache implements NodeCache {
     private static final int DEFAULT_CAPACITY = 4096;
 
     private final int capacity;
-    private final ConcurrentHashMap<Integer, JsonNode> cache;
+    private final ConcurrentHashMap<CacheKey, DecodedValue> cache;
     private boolean cacheFull = false;
 
     public CHMCache() {
@@ -28,14 +26,13 @@ public CHMCache(int capacity) {
     }
 
     @Override
-    public JsonNode get(int key, Loader loader) throws IOException {
-        Integer k = key;
-        JsonNode value = cache.get(k);
+    public DecodedValue get(CacheKey key, Loader loader) throws IOException {
+        DecodedValue value = cache.get(key);
         if (value == null) {
             value = loader.load(key);
             if (!cacheFull) {
                 if (cache.size() < capacity) {
-                    cache.put(k, value);
+                    cache.put(key, value);
                 } else {
                     cacheFull = true;
                 }

src/main/java/com/maxmind/db/CacheKey.java

@@ -0,0 +1,59 @@
+package com.maxmind.db;
+
+public final class CacheKey<T> {
+    private final int offset;
+    private final Class<T> cls;
+    private final java.lang.reflect.Type type;
+
+    CacheKey(int offset, Class<T> cls, java.lang.reflect.Type type) {
+        this.offset = offset;
+        this.cls = cls;
+        this.type = type;
+    }
+
+    int getOffset() {
+        return this.offset;
+    }
+
+    Class<T> getCls() {
+        return this.cls;
+    }
+
+    java.lang.reflect.Type getType() {
+        return this.type;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o == null) {
+            return false;
+        }
+
+        CacheKey other = (CacheKey) o;
+
+        if (this.offset != other.offset) {
+            return false;
+        }
+
+        if (this.cls == null) {
+            if (other.cls != null) {
+                return false;
+            }
+        } else if (!this.cls.equals(other.cls)) {
+            return false;
+        }
+
+        if (this.type == null) {
+            return other.type == null;
+        }
+        return this.type.equals(other.type);
+    }
+
+    @Override
+    public int hashCode() {
+        int result = offset;
+        result = 31 * result + (cls == null ? 0 : cls.hashCode());
+        result = 31 * result + (type == null ? 0 : type.hashCode());
+        return result;
+    }
+}

src/main/java/com/maxmind/db/CachedConstructor.java

@@ -0,0 +1,39 @@
+package com.maxmind.db;
+
+import java.lang.reflect.Constructor;
+import java.util.Map;
+
+final class CachedConstructor<T> {
+    private final Constructor<T> constructor;
+    private final Class<?>[] parameterTypes;
+    private final java.lang.reflect.Type[] parameterGenericTypes;
+    private final Map<String, Integer> parameterIndexes;
+
+    CachedConstructor(
+            Constructor<T> constructor,
+            Class<?>[] parameterTypes,
+            java.lang.reflect.Type[] parameterGenericTypes,
+            Map<String, Integer> parameterIndexes
+    ) {
+        this.constructor = constructor;
+        this.parameterTypes = parameterTypes;
+        this.parameterGenericTypes = parameterGenericTypes;
+        this.parameterIndexes = parameterIndexes;
+    }
+
+    Constructor<T> getConstructor() {
+        return this.constructor;
+    }
+
+    Class<?>[] getParameterTypes() {
+        return this.parameterTypes;
+    }
+
+    java.lang.reflect.Type[] getParameterGenericTypes() {
+        return this.parameterGenericTypes;
+    }
+
+    Map<String, Integer> getParameterIndexes() {
+        return this.parameterIndexes;
+    }
+}

src/main/java/com/maxmind/db/ConstructorNotFoundException.java

@@ -0,0 +1,13 @@
+package com.maxmind.db;
+
+/**
+ * Signals that no annotated constructor was found. You should annotate a
+ * constructor in the class with the MaxMindDbConstructor annotation.
+ */
+public class ConstructorNotFoundException extends RuntimeException {
+    private static final long serialVersionUID = 1L;
+
+    ConstructorNotFoundException(String message) {
+        super(message);
+    }
+}

src/main/java/com/maxmind/db/CtrlData.java

@@ -0,0 +1,31 @@
+package com.maxmind.db;
+
+final class CtrlData {
+    private final Type type;
+    private final int ctrlByte;
+    private final int offset;
+    private final int size;
+
+    CtrlData(Type type, int ctrlByte, int offset, int size) {
+        this.type = type;
+        this.ctrlByte = ctrlByte;
+        this.offset = offset;
+        this.size = size;
+    }
+
+    public Type getType() {
+        return this.type;
+    }
+
+    public int getCtrlByte() {
+        return this.ctrlByte;
+    }
+
+    public int getOffset() {
+        return this.offset;
+    }
+
+    public int getSize() {
+        return this.size;
+    }
+}