Skip to content

Commit d963dd3

Browse files
oschwaldoschwald
committed
Added Javadocs and renamed exception
1 parent 1549fbd commit d963dd3

8 files changed

Lines changed: 120 additions & 73 deletions

File tree

‎sample/Benchmark.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55

66
import com.fasterxml.jackson.databind.JsonNode;
77
import com.google.common.net.InetAddresses;
8-
import com.maxmind.maxminddb.MaxMindDbException;
8+
import com.maxmind.maxminddb.InvalidDatabaseException;
99
import com.maxmind.maxminddb.Reader;
1010
import com.maxmind.maxminddb.Reader.FileMode;
1111

1212
public class Benchmark {
1313

1414
public static void main(String[] args) throws IOException,
15-
MaxMindDbException {
15+
InvalidDatabaseException {
1616
File file = new File("GeoIP2-City.mmdb");
1717

1818
Reader r = new Reader(file, FileMode.MEMORY_MAPPED);

‎src/main/java/com/maxmind/maxminddb/Decoder.java‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ void setOffset(long offset) {
7979
this.DEBUG = System.getenv().get("MAXMIND_DB_DECODER_DEBUG") != null;
8080
}
8181

82-
Result decode(long offset) throws MaxMindDbException, IOException {
82+
Result decode(long offset) throws IOException {
8383
ByteBuffer buffer = this.threadBuffer.get();
8484

8585
buffer.position((int) offset);
@@ -126,7 +126,7 @@ Result decode(long offset) throws MaxMindDbException, IOException {
126126
int typeNum = nextByte + 7;
127127

128128
if (typeNum < 8) {
129-
throw new MaxMindDbException(
129+
throw new InvalidDatabaseException(
130130
"Something went horribly wrong in the decoder. An extended type "
131131
+ "resolved to a type number < 8 (" + typeNum
132132
+ ")");
@@ -193,8 +193,8 @@ Result decode(long offset) throws MaxMindDbException, IOException {
193193
BigIntegerNode uint128 = this.decodeBigInteger(size);
194194
return new Result(uint128, new_offset);
195195
default:
196-
throw new MaxMindDbException("Unknown or unexpected type: "
197-
+ type.name());
196+
throw new InvalidDatabaseException(
197+
"Unknown or unexpected type: " + type.name());
198198

199199
}
200200
}
@@ -293,8 +293,7 @@ private Result decodeBoolean(long size, long offset) {
293293
return new Result(b, offset);
294294
}
295295

296-
private Result decodeArray(long size, long offset)
297-
throws MaxMindDbException, IOException {
296+
private Result decodeArray(long size, long offset) throws IOException {
298297
if (this.DEBUG) {
299298
Log.debug("Array size", size);
300299
}
@@ -318,8 +317,7 @@ private Result decodeArray(long size, long offset)
318317
return new Result(array, offset);
319318
}
320319

321-
private Result decodeMap(long size, long offset) throws MaxMindDbException,
322-
IOException {
320+
private Result decodeMap(long size, long offset) throws IOException {
323321
if (this.DEBUG) {
324322
Log.debug("Map size", size);
325323
}

‎src/main/java/com/maxmind/maxminddb/InvalidDatabaseException.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package com.maxmind.maxminddb;
2+
3+
import java.io.IOException;
4+
5+
/**
6+
* Signals that there was an issue reading from the MaxMind DB file due to
7+
* unexpected data formatting. This generally suggests that the database is
8+
* corrupt or otherwise not in a format supported by the reader.
9+
*/
10+
public class InvalidDatabaseException extends IOException {
11+
12+
private static final long serialVersionUID = 6161763462364823003L;
13+
14+
/**
15+
* @param message
16+
* A message describing the reason why the exception was thrown.
17+
*/
18+
public InvalidDatabaseException(String message) {
19+
super(message);
20+
}
21+
22+
/**
23+
* @param message
24+
* A message describing the reason why the exception was thrown.
25+
* @param cause
26+
* The cause of the exception.
27+
*/
28+
public InvalidDatabaseException(String message, Throwable cause) {
29+
super(message, cause);
30+
}
31+
}

‎src/main/java/com/maxmind/maxminddb/MaxMindDbException.java‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

‎src/main/java/com/maxmind/maxminddb/Reader.java‎

Lines changed: 64 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77

88
import com.fasterxml.jackson.databind.JsonNode;
99

10+
/**
11+
* Instances of this class provide a reader for the MaxMind DB format. IP
12+
* addresses can be looked up using the <code>get</code> method.
13+
*/
1014
public final class Reader {
1115
private static final int DATA_SECTION_SEPARATOR_SIZE = 16;
1216
private static final byte[] METADATA_START_MARKER = { (byte) 0xAB,
@@ -18,21 +22,49 @@ public final class Reader {
1822
private final Metadata metadata;
1923
private final ThreadBuffer threadBuffer;
2024

25+
/**
26+
* The file mode to use when opening a MaxMind DB.
27+
*/
2128
public enum FileMode {
22-
MEMORY_MAPPED, IN_MEMORY
29+
/**
30+
* The default file mode. This maps the database to virtual memory. This
31+
* often provides similar performance to loading the database into real
32+
* memory without the overhead.
33+
*/
34+
MEMORY_MAPPED,
35+
/**
36+
* Loads the database into memory when the reader is constructed.
37+
*/
38+
IN_MEMORY
2339
}
2440

25-
public Reader(File database) throws MaxMindDbException, IOException {
41+
/**
42+
* Constructs a Reader for the MaxMind DB format. The file passed to it must
43+
* be a valid MaxMind DB file such as a GeoIP2 database file.
44+
*
45+
* @param database
46+
* the MaxMind DB file to use.
47+
* @throws IOException
48+
* if there is an error opening or reading from the file.
49+
*/
50+
public Reader(File database) throws IOException {
2651
this(database, FileMode.MEMORY_MAPPED);
2752
}
2853

29-
// XXX - loading the file into memory doesn't really provide any performance
30-
// gains on my machine. Consider whether it is even worth providing the
31-
// option.
32-
public Reader(File database, FileMode mode) throws MaxMindDbException,
33-
IOException {
54+
/**
55+
* Constructs a Reader for the MaxMind DB format. The file passed to it must
56+
* be a valid MaxMind DB file such as a GeoIP2 database file.
57+
*
58+
* @param database
59+
* the MaxMind DB file to use.
60+
* @param fileMode
61+
* the mode to open the file with.
62+
* @throws IOException
63+
* if there is an error opening or reading from the file.
64+
*/
65+
public Reader(File database, FileMode fileMode) throws IOException {
3466
this.DEBUG = System.getenv().get("MAXMIND_DB_READER_DEBUG") != null;
35-
this.threadBuffer = new ThreadBuffer(database, mode);
67+
this.threadBuffer = new ThreadBuffer(database, fileMode);
3668

3769
/*
3870
* We need to make sure that whatever chunk we read will have the
@@ -51,7 +83,7 @@ public Reader(File database, FileMode mode) throws MaxMindDbException,
5183
long start = this.findMetadataStart();
5284

5385
if (start < 0) {
54-
throw new MaxMindDbException(
86+
throw new InvalidDatabaseException(
5587
"Could not find a MaxMind DB metadata marker in this file ("
5688
+ database.getName()
5789
+ "). Is this a valid MaxMind DB file?");
@@ -69,10 +101,18 @@ public Reader(File database, FileMode mode) throws MaxMindDbException,
69101
}
70102
}
71103

72-
public JsonNode get(InetAddress address) throws MaxMindDbException,
73-
IOException {
104+
/**
105+
* Looks up the <code>address</code> in the MaxMind DB.
106+
*
107+
* @param ipAddress
108+
* the IP address to look up.
109+
* @return the record for the IP address.
110+
* @throws IOException
111+
* if a file I/O error occurs.
112+
*/
113+
public JsonNode get(InetAddress ipAddress) throws IOException {
74114

75-
long pointer = this.findAddressInTree(address);
115+
long pointer = this.findAddressInTree(ipAddress);
76116

77117
if (pointer == 0) {
78118
return null;
@@ -83,7 +123,7 @@ public JsonNode get(InetAddress address) throws MaxMindDbException,
83123
}
84124

85125
private long findAddressInTree(InetAddress address)
86-
throws MaxMindDbException {
126+
throws InvalidDatabaseException {
87127
byte[] rawAddress = address.getAddress();
88128

89129
if (this.DEBUG) {
@@ -138,10 +178,11 @@ long record = this.readNode(nodeNum, bit);
138178
nodeNum = record;
139179
}
140180

141-
throw new MaxMindDbException("Something bad happened");
181+
throw new InvalidDatabaseException("Something bad happened");
142182
}
143183

144-
private long readNode(long nodeNumber, int index) throws MaxMindDbException {
184+
private long readNode(long nodeNumber, int index)
185+
throws InvalidDatabaseException {
145186
ByteBuffer buffer = this.threadBuffer.get();
146187
int baseOffset = (int) nodeNumber * this.metadata.nodeByteSize;
147188
buffer.position(baseOffset);
@@ -164,13 +205,12 @@ private long readNode(long nodeNumber, int index) throws MaxMindDbException {
164205
buffer.position(baseOffset + index * 4);
165206
return Decoder.decodeLong(buffer, 0, 4);
166207
default:
167-
throw new MaxMindDbException("Unknown record size: "
208+
throw new InvalidDatabaseException("Unknown record size: "
168209
+ this.metadata.recordSize);
169210
}
170211
}
171212

172-
private JsonNode resolveDataPointer(long pointer)
173-
throws MaxMindDbException, IOException {
213+
private JsonNode resolveDataPointer(long pointer) throws IOException {
174214
long resolved = (pointer - this.metadata.nodeCount)
175215
+ this.metadata.searchTreeSize;
176216

@@ -216,6 +256,12 @@ Metadata getMetadata() {
216256
return this.metadata;
217257
}
218258

259+
/**
260+
* Closes the MaxMind DB and returns resources to the system.
261+
*
262+
* @throws IOException
263+
* if an I/O error occurs.
264+
*/
219265
public void close() throws IOException {
220266
this.threadBuffer.close();
221267
}

‎src/test/java/com/maxmind/maxminddb/DecoderTest.java‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -318,70 +318,70 @@ static Map<ArrayNode, byte[]> arrays() {
318318
}
319319

320320
@Test
321-
public void testUint16() throws MaxMindDbException, IOException {
321+
public void testUint16() throws InvalidDatabaseException, IOException {
322322
DecoderTest.testTypeDecoding(Decoder.Type.UINT16, uint16());
323323
}
324324

325325
@Test
326-
public void testUint32() throws MaxMindDbException, IOException {
326+
public void testUint32() throws InvalidDatabaseException, IOException {
327327
DecoderTest.testTypeDecoding(Decoder.Type.UINT32, uint32());
328328
}
329329

330330
@Test
331-
public void testInt32() throws MaxMindDbException, IOException {
331+
public void testInt32() throws InvalidDatabaseException, IOException {
332332
DecoderTest.testTypeDecoding(Decoder.Type.INT32, int32());
333333
}
334334

335335
@Test
336-
public void testUint64() throws MaxMindDbException, IOException {
336+
public void testUint64() throws InvalidDatabaseException, IOException {
337337
DecoderTest.testTypeDecoding(Decoder.Type.UINT64, largeUint(64));
338338
}
339339

340340
@Test
341-
public void testUint128() throws MaxMindDbException, IOException {
341+
public void testUint128() throws InvalidDatabaseException, IOException {
342342
DecoderTest.testTypeDecoding(Decoder.Type.UINT128, largeUint(128));
343343
}
344344

345345
@Test
346-
public void testDoubles() throws MaxMindDbException, IOException {
346+
public void testDoubles() throws InvalidDatabaseException, IOException {
347347
DecoderTest
348348
.testTypeDecoding(Decoder.Type.DOUBLE, DecoderTest.doubles());
349349
}
350350

351351
@Test
352-
public void testPointers() throws MaxMindDbException, IOException {
352+
public void testPointers() throws InvalidDatabaseException, IOException {
353353
DecoderTest.testTypeDecoding(Decoder.Type.POINTER, pointers());
354354
}
355355

356356
@Test
357-
public void testStrings() throws MaxMindDbException, IOException {
357+
public void testStrings() throws InvalidDatabaseException, IOException {
358358
DecoderTest.testTypeDecoding(Decoder.Type.UTF8_STRING,
359359
DecoderTest.strings());
360360
}
361361

362362
@Test
363-
public void testBooleans() throws MaxMindDbException, IOException {
363+
public void testBooleans() throws InvalidDatabaseException, IOException {
364364
DecoderTest.testTypeDecoding(Decoder.Type.BOOLEAN,
365365
DecoderTest.booleans());
366366
}
367367

368368
@Test
369-
public void testBytes() throws MaxMindDbException, IOException {
369+
public void testBytes() throws InvalidDatabaseException, IOException {
370370
DecoderTest.testTypeDecoding(Decoder.Type.BYTES, DecoderTest.bytes());
371371
}
372372

373373
@Test
374-
public void testMaps() throws MaxMindDbException, IOException {
374+
public void testMaps() throws InvalidDatabaseException, IOException {
375375
DecoderTest.testTypeDecoding(Decoder.Type.MAP, DecoderTest.maps());
376376
}
377377

378378
@Test
379-
public void testArrays() throws MaxMindDbException, IOException {
379+
public void testArrays() throws InvalidDatabaseException, IOException {
380380
DecoderTest.testTypeDecoding(Decoder.Type.ARRAY, DecoderTest.arrays());
381381
}
382382

383383
static <T> void testTypeDecoding(Decoder.Type type, Map<T, byte[]> tests)
384-
throws MaxMindDbException, IOException {
384+
throws InvalidDatabaseException, IOException {
385385

386386
for (Map.Entry<T, byte[]> entry : tests.entrySet()) {
387387
T expect = entry.getKey();

‎src/test/java/com/maxmind/maxminddb/PointerTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
public class PointerTest {
1515
@SuppressWarnings("static-method")
1616
@Test
17-
public void testWithPointers() throws MaxMindDbException, IOException {
17+
public void testWithPointers() throws InvalidDatabaseException, IOException {
1818
File file = new File("test-data/pointer.bin");
1919
ThreadBuffer ptf = new ThreadBuffer(file, FileMode.IN_MEMORY);
2020
try {

‎src/test/java/com/maxmind/maxminddb/ReaderTest.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ public class ReaderTest {
1818
private final ObjectMapper om = new ObjectMapper();
1919

2020
@Test
21-
public void test() throws MaxMindDbException, IOException {
21+
public void test() throws InvalidDatabaseException, IOException {
2222
for (long recordSize : new long[] { 24 }) { // 24, 28, 32 }) {
2323
for (int ipVersion : new int[] { 4, 6 }) {
2424
String fileName = "test-data/Test-IPv" + ipVersion + "-"
@@ -57,7 +57,7 @@ private void testMetadata(Reader reader, int ipVersion, long recordSize) {
5757
}
5858

5959
private void testIpV4(Reader reader, String fileName)
60-
throws MaxMindDbException, IOException {
60+
throws InvalidDatabaseException, IOException {
6161

6262
for (int i = 0; i <= 5; i++) {
6363
String address = "1.1.1." + (int) Math.pow(2, i);
@@ -93,7 +93,7 @@ private void testIpV4(Reader reader, String fileName)
9393

9494
// XXX - logic could be combined with above
9595
private void testIpV6(Reader reader, String fileName)
96-
throws MaxMindDbException, IOException {
96+
throws InvalidDatabaseException, IOException {
9797
String[] subnets = new String[] { "::1:ffff:ffff", "::2:0:0",
9898
"::2:0:40", "::2:0:50", "::2:0:58" };
9999

0 commit comments

Comments
 (0)