diff --git a/checkstyle.xml b/checkstyle.xml index e40ecfc1..285c8d11 100644 --- a/checkstyle.xml +++ b/checkstyle.xml @@ -314,18 +314,18 @@ - + + @@ -333,20 +333,24 @@ - + org.apache.maven.plugins maven-javadoc-plugin 3.6.3 + + -missing + diff --git a/src/main/java/com/maxmind/db/CHMCache.java b/src/main/java/com/maxmind/db/CHMCache.java index 4989cdc0..f9f63292 100644 --- a/src/main/java/com/maxmind/db/CHMCache.java +++ b/src/main/java/com/maxmind/db/CHMCache.java @@ -16,10 +16,20 @@ public class CHMCache implements NodeCache { private final ConcurrentHashMap cache; private boolean cacheFull = false; + /** + * Creates a new cache with the default capacity. + */ public CHMCache() { this(DEFAULT_CAPACITY); } + /** + * Creates a new cache with the specified capacity. + * + * @param capacity + * the maximum number of elements the cache can hold before + * starting to evict them + */ public CHMCache(int capacity) { this.capacity = capacity; this.cache = new ConcurrentHashMap<>(capacity); diff --git a/src/main/java/com/maxmind/db/CacheKey.java b/src/main/java/com/maxmind/db/CacheKey.java index 7f060b01..d62c0843 100644 --- a/src/main/java/com/maxmind/db/CacheKey.java +++ b/src/main/java/com/maxmind/db/CacheKey.java @@ -1,5 +1,12 @@ package com.maxmind.db; +/** + * {@code CacheKey} is used as a key in the data-section cache. It contains the offset of the + * value in the database file, the class of the value, and the type + * of the value. + * + * @param the type of value + */ public final class CacheKey { private final int offset; private final Class cls; diff --git a/src/main/java/com/maxmind/db/DatabaseRecord.java b/src/main/java/com/maxmind/db/DatabaseRecord.java index 3cb2336f..6779408b 100644 --- a/src/main/java/com/maxmind/db/DatabaseRecord.java +++ b/src/main/java/com/maxmind/db/DatabaseRecord.java @@ -5,6 +5,8 @@ /** * DatabaseRecord represents the data and metadata associated with a database * lookup. + * + * @param the type to deserialize the returned value to */ public final class DatabaseRecord { private final T data; @@ -23,8 +25,9 @@ public DatabaseRecord(T data, InetAddress ipAddress, int prefixLength) { } /** - * @return the data for the record in the database. The record will be - * null if there was no data for the address in the database. + * @return the data for the record in the database. The record will be + * null if there was no data for the address in the + * database. */ public T getData() { return data; @@ -32,8 +35,8 @@ public T getData() { /** * @return the network associated with the record in the database. This is - * the largest network where all of the IPs in the network have the same - * data. + * the largest network where all of the IPs in the network have the same + * data. */ public Network getNetwork() { return network; diff --git a/src/main/java/com/maxmind/db/DecodedValue.java b/src/main/java/com/maxmind/db/DecodedValue.java index c7708183..8a6f4454 100644 --- a/src/main/java/com/maxmind/db/DecodedValue.java +++ b/src/main/java/com/maxmind/db/DecodedValue.java @@ -1,5 +1,9 @@ package com.maxmind.db; +/** + * {@code DecodedValue} is a wrapper for the decoded value and the number of bytes used + * to decode it. + */ public final class DecodedValue { final Object value; diff --git a/src/main/java/com/maxmind/db/InvalidNetworkException.java b/src/main/java/com/maxmind/db/InvalidNetworkException.java index 6103e454..d88359c0 100644 --- a/src/main/java/com/maxmind/db/InvalidNetworkException.java +++ b/src/main/java/com/maxmind/db/InvalidNetworkException.java @@ -2,7 +2,14 @@ import java.net.InetAddress; +/** + * This is a custom exception that is thrown when the user attempts to use an + * IPv6 address in an IPv4-only database. + */ public class InvalidNetworkException extends Exception { + /** + * @param ip the IP address that was used + */ public InvalidNetworkException(InetAddress ip) { super("you attempted to use an IPv6 network in an IPv4-only database: " + ip.toString()); } diff --git a/src/main/java/com/maxmind/db/MaxMindDbConstructor.java b/src/main/java/com/maxmind/db/MaxMindDbConstructor.java index def9da19..4a915773 100644 --- a/src/main/java/com/maxmind/db/MaxMindDbConstructor.java +++ b/src/main/java/com/maxmind/db/MaxMindDbConstructor.java @@ -3,6 +3,11 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; +/** + * {@code MaxMindDbConstructor} is an annotation that can be used to mark a constructor + * that should be used to create an instance of a class when decoding a MaxMind + * DB file. + */ @Retention(RetentionPolicy.RUNTIME) public @interface MaxMindDbConstructor { } diff --git a/src/main/java/com/maxmind/db/MaxMindDbParameter.java b/src/main/java/com/maxmind/db/MaxMindDbParameter.java index a20cff1d..b04f9ba4 100644 --- a/src/main/java/com/maxmind/db/MaxMindDbParameter.java +++ b/src/main/java/com/maxmind/db/MaxMindDbParameter.java @@ -3,7 +3,15 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; +/** + * Interface for a MaxMind DB parameter. This is used to mark a parameter that + * should be used to create an instance of a class when decoding a MaxMind DB + * file. + */ @Retention(RetentionPolicy.RUNTIME) public @interface MaxMindDbParameter { + /** + * @return the name of the parameter in the MaxMind DB file + */ String name(); } diff --git a/src/main/java/com/maxmind/db/Metadata.java b/src/main/java/com/maxmind/db/Metadata.java index 46a6301c..3c31f469 100644 --- a/src/main/java/com/maxmind/db/Metadata.java +++ b/src/main/java/com/maxmind/db/Metadata.java @@ -5,6 +5,9 @@ import java.util.List; import java.util.Map; +/** + * {@code Metadata} holds data associated with the database itself. + */ public final class Metadata { private final int binaryFormatMajorVersion; private final int binaryFormatMinorVersion; @@ -27,27 +30,40 @@ public final class Metadata { private final int searchTreeSize; + /** + * Constructs a {@code Metadata} object. + * + * @param binaryFormatMajorVersion The major version number for the database's + * binary format. + * @param binaryFormatMinorVersion The minor version number for the database's + * binary format. + * @param buildEpoch The date of the database build. + * @param databaseType A string that indicates the structure of each + * data record associated with an IP address. + * The actual definition of these structures is + * left up to the database creator. + * @param languages List of languages supported by the database. + * @param description Map from language code to description in that + * language. + * @param ipVersion Whether the database contains IPv4 or IPv6 + * address data. The only possible values are 4 + * and 6. + * @param nodeCount The number of nodes in the search tree. + * @param recordSize The number of bits in a record in the search + * tree. Note that each node consists of two + * records. + */ @MaxMindDbConstructor public Metadata( - @MaxMindDbParameter(name = "binary_format_major_version") - int binaryFormatMajorVersion, - @MaxMindDbParameter(name = "binary_format_minor_version") - int binaryFormatMinorVersion, - @MaxMindDbParameter(name = "build_epoch") - BigInteger buildEpoch, - @MaxMindDbParameter(name = "database_type") - String databaseType, - @MaxMindDbParameter(name = "languages") - List languages, - @MaxMindDbParameter(name = "description") - Map description, - @MaxMindDbParameter(name = "ip_version") - int ipVersion, - @MaxMindDbParameter(name = "node_count") - long nodeCount, - @MaxMindDbParameter(name = "record_size") - int recordSize - ) { + @MaxMindDbParameter(name = "binary_format_major_version") int binaryFormatMajorVersion, + @MaxMindDbParameter(name = "binary_format_minor_version") int binaryFormatMinorVersion, + @MaxMindDbParameter(name = "build_epoch") BigInteger buildEpoch, + @MaxMindDbParameter(name = "database_type") String databaseType, + @MaxMindDbParameter(name = "languages") List languages, + @MaxMindDbParameter(name = "description") Map description, + @MaxMindDbParameter(name = "ip_version") int ipVersion, + @MaxMindDbParameter(name = "node_count") long nodeCount, + @MaxMindDbParameter(name = "record_size") int recordSize) { this.binaryFormatMajorVersion = binaryFormatMajorVersion; this.binaryFormatMinorVersion = binaryFormatMinorVersion; this.buildEpoch = buildEpoch; @@ -85,8 +101,8 @@ public Date getBuildDate() { /** * @return a string that indicates the structure of each data record - * associated with an IP address. The actual definition of these - * structures is left up to the database creator. + * associated with an IP address. The actual definition of these + * structures is left up to the database creator. */ public String getDatabaseType() { return this.databaseType; @@ -101,7 +117,7 @@ public Map getDescription() { /** * @return whether the database contains IPv4 or IPv6 address data. The only - * possible values are 4 and 6. + * possible values are 4 and 6. */ public int getIpVersion() { return this.ipVersion; @@ -130,7 +146,7 @@ int getNodeCount() { /** * @return the number of bits in a record in the search tree. Note that each - * node consists of two records. + * node consists of two records. */ int getRecordSize() { return this.recordSize; @@ -151,11 +167,11 @@ int getSearchTreeSize() { @Override public String toString() { return "Metadata [binaryFormatMajorVersion=" - + this.binaryFormatMajorVersion + ", binaryFormatMinorVersion=" - + this.binaryFormatMinorVersion + ", buildEpoch=" - + this.buildEpoch + ", databaseType=" + this.databaseType - + ", description=" + this.description + ", ipVersion=" - + this.ipVersion + ", nodeCount=" + this.nodeCount - + ", recordSize=" + this.recordSize + "]"; + + this.binaryFormatMajorVersion + ", binaryFormatMinorVersion=" + + this.binaryFormatMinorVersion + ", buildEpoch=" + + this.buildEpoch + ", databaseType=" + this.databaseType + + ", description=" + this.description + ", ipVersion=" + + this.ipVersion + ", nodeCount=" + this.nodeCount + + ", recordSize=" + this.recordSize + "]"; } } diff --git a/src/main/java/com/maxmind/db/Network.java b/src/main/java/com/maxmind/db/Network.java index aee5c84f..32033e0a 100644 --- a/src/main/java/com/maxmind/db/Network.java +++ b/src/main/java/com/maxmind/db/Network.java @@ -54,15 +54,15 @@ public InetAddress getNetworkAddress() { /** * @return The prefix length is the number of leading 1 bits in the subnet - * mask. Sometimes also known as netmask length. + * mask. Sometimes also known as netmask length. */ public int getPrefixLength() { return prefixLength; } - /*** + /** * @return A string representation of the network in CIDR notation, e.g., - * 1.2.3.0/24 or 2001::/8. + * 1.2.3.0/24 or 2001::/8. */ public String toString() { return getNetworkAddress().getHostAddress() + "/" + prefixLength; diff --git a/src/main/java/com/maxmind/db/Networks.java b/src/main/java/com/maxmind/db/Networks.java index 4214357c..b06dfffb 100644 --- a/src/main/java/com/maxmind/db/Networks.java +++ b/src/main/java/com/maxmind/db/Networks.java @@ -11,7 +11,7 @@ /** * Instances of this class provide an iterator over the networks in a database. * The iterator will return a {@link DatabaseRecord} for each network. - * + * * @param The type of data returned by the iterator. */ public final class Networks implements Iterator> { @@ -24,6 +24,7 @@ public final class Networks implements Iterator> { /** * Constructs a Networks instance. + * * @param reader The reader object. * @param includeAliasedNetworks The boolean to include aliased networks. * @param typeParameterClass The type of data returned by the iterator. @@ -36,6 +37,7 @@ public final class Networks implements Iterator> { /** * Constructs a Networks instance. + * * @param reader The reader object. * @param includeAliasedNetworks The boolean to include aliased networks. * @param nodes The initial nodes array to start Networks iterator with. @@ -60,6 +62,7 @@ public final class Networks implements Iterator> { /** * Constructs a Networks instance with includeAliasedNetworks set to false by default. + * * @param reader The reader object. * @param typeParameterClass The type of data returned by the iterator. */ @@ -69,6 +72,7 @@ public final class Networks implements Iterator> { /** * Returns the next DataRecord. + * * @return The next DataRecord. * @throws NetworksIterationException An exception when iterating over the networks. */ @@ -118,6 +122,7 @@ private boolean isInIpv4Subtree(byte[] ip) { * hasNext prepares the next network for reading with the Network method. It * returns true if there is another network to be processed and false if there * are no more networks. + * * @return boolean True if there is another network to be processed. * @throws NetworksIterationException Exception while iterating over the networks. */ @@ -169,6 +174,7 @@ static class NetworkNode { /** * Constructs a network node for internal use. + * * @param ip The ip address of the node. * @param prefix The prefix of the node. * @param pointer The node number diff --git a/src/main/java/com/maxmind/db/NetworksIterationException.java b/src/main/java/com/maxmind/db/NetworksIterationException.java index 8e6eee39..ad24a88c 100644 --- a/src/main/java/com/maxmind/db/NetworksIterationException.java +++ b/src/main/java/com/maxmind/db/NetworksIterationException.java @@ -9,7 +9,7 @@ * This exception extends RuntimeException because it is thrown by the iterator * methods in {@link Networks}. *

- * + * * @see Networks */ public class NetworksIterationException extends RuntimeException { diff --git a/src/main/java/com/maxmind/db/NoCache.java b/src/main/java/com/maxmind/db/NoCache.java index 69e879c4..f169e3b3 100644 --- a/src/main/java/com/maxmind/db/NoCache.java +++ b/src/main/java/com/maxmind/db/NoCache.java @@ -16,7 +16,10 @@ private NoCache() { public DecodedValue get(CacheKey key, Loader loader) throws IOException { return loader.load(key); } - + + /** + * @return the singleton instance of the NoCache class + */ public static NoCache getInstance() { return INSTANCE; } diff --git a/src/main/java/com/maxmind/db/NodeCache.java b/src/main/java/com/maxmind/db/NodeCache.java index e6baf2a8..d7235813 100644 --- a/src/main/java/com/maxmind/db/NodeCache.java +++ b/src/main/java/com/maxmind/db/NodeCache.java @@ -2,12 +2,37 @@ import java.io.IOException; +/** + * NodeCache is an interface for a cache that stores decoded values from the + * data section of the database. + */ public interface NodeCache { - + /** + * A loader is used to load a value for a key that is not in the cache. + */ interface Loader { + /** + * @param key + * the key to load + * @return the value for the key + * @throws IOException + * if there is an error loading the value + */ DecodedValue load(CacheKey key) throws IOException; } + /** + * This method returns the value for the key. If the key is not in the cache + * then the loader is called to load the value. + * + * @param key + * the key to look up + * @param loader + * the loader to use if the key is not in the cache + * @return the value for the key + * @throws IOException + * if there is an error loading the value + */ DecodedValue get(CacheKey key, Loader loader) throws IOException; } diff --git a/src/main/java/com/maxmind/db/Reader.java b/src/main/java/com/maxmind/db/Reader.java index 3f83a5ad..1b8b84b2 100644 --- a/src/main/java/com/maxmind/db/Reader.java +++ b/src/main/java/com/maxmind/db/Reader.java @@ -163,7 +163,7 @@ int getIpv4Start() { * @param ipAddress the IP address to look up. * @param cls the class of object to populate. * @return the record for the IP address. If there is no data for the - * address, the non-null {@link DatabaseRecord} will still be returned. + * address, the non-null {@link DatabaseRecord} will still be returned. * @throws IOException if a file I/O error occurs. */ public DatabaseRecord getRecord(InetAddress ipAddress, Class cls) @@ -197,7 +197,7 @@ int record = traverseResult[0]; * Please note that a MaxMind DB may map IPv4 networks into several locations * in an IPv6 database. networks() iterates over the canonical locations and * not the aliases. To include the aliases, you can set includeAliasedNetworks to true. - * + * * @param Represents the data type(e.g., Map, HastMap, etc.). * @param typeParameterClass The type of data returned by the iterator. * @return Networks The Networks iterator. @@ -216,7 +216,7 @@ public Networks networks(Class typeParameterClass) throws * in an IPv6 database. This iterator will iterate over all of these locations * separately. To set the iteration over the IPv4 networks once, use the * includeAliasedNetworks option. - * + * * @param Represents the data type(e.g., Map, HastMap, etc.). * @param includeAliasedNetworks Enable including aliased networks. * @return Networks The Networks iterator. @@ -283,6 +283,7 @@ private int findIpV4StartNode(ByteBuffer buffer) * in an IPv6 database. This iterator will iterate over all of these locations * separately. To only iterate over the IPv4 networks once, use the * includeAliasedNetworks option. + * * @param Represents the data type(e.g., Map, HastMap, etc.). * @param network Specifies the network to be iterated. * @param includeAliasedNetworks Boolean for including aliased networks. @@ -329,6 +330,7 @@ public Networks networksWithin( /** * Returns the node number and the prefix for the network. + * * @param ip The ip address to traverse. * @param bitCount The prefix. * @return int[]