Merge pull request #733 from maxmind/greg/docs-windows-memory-map-lock

Clarify Windows memory-map file locking and fix Javadoc issues

Author: horgh

README.md

@@ -286,6 +286,24 @@ Maven, you must
 Failure to do so will result in `InvalidDatabaseException` exceptions being
 thrown when querying the database.
 
+### File Lock on Windows ###
+
+By default, the `DatabaseReader` uses the `MEMORY_MAPPED` file mode, which
+memory maps the database file. On Windows, a live memory mapping may prevent
+the file from being renamed, replaced, or deleted. This is not a Java
+`FileLock`, but it can have similar effects when updating a database file in
+place.
+
+Closing the `DatabaseReader` releases its reference to the mapped buffer, but
+Java does not provide a supported way to unmap the underlying
+`MappedByteBuffer` immediately. The mapping remains valid until the buffer
+becomes unreachable and is garbage collected.
+
+To avoid this behavior, configure the `Builder` with `FileMode.MEMORY`. If you
+must use `MEMORY_MAPPED`, close and dereference the `DatabaseReader` before
+replacing the file. You may call `System.gc()` to encourage earlier cleanup,
+but garbage collection is not guaranteed to run immediately.
+
 ## Database Example ##
 
 ### City ###

lychee.toml

@@ -5,7 +5,7 @@
 #   lychee './**/*.md' './src/**/*.java' './pom.xml'
 
 # Include URL fragments in checks
-include_fragments = true
+include_fragments = "full"
 
 # Don't allow any redirects, so links that have moved are surfaced and updated
 # to their canonical destination.

mise.lock

@@ -42,7 +42,7 @@ Optional<CityResponse> tryCity(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoIP Anonymous IP.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return a AnonymousIpResponse for the requested IP address.
+     * @return an AnonymousIpResponse for the requested IP address.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -53,7 +53,7 @@ AnonymousIpResponse anonymousIp(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoIP Anonymous IP.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return a AnonymousIpResponse for the requested IP address or empty if it is not in the DB.
+     * @return an AnonymousIpResponse for the requested IP address or empty if it is not in the DB.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -64,7 +64,7 @@ Optional<AnonymousIpResponse> tryAnonymousIp(InetAddress ipAddress) throws IOExc
      * Look up an IP address in a GeoIP Anonymous Plus.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return a AnonymousPlusResponse for the requested IP address.
+     * @return an AnonymousPlusResponse for the requested IP address.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -75,7 +75,8 @@ AnonymousPlusResponse anonymousPlus(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoIP Anonymous Plus.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return a AnonymousPlusResponse for the requested IP address or empty if it is not in the DB.
+     * @return an AnonymousPlusResponse for the requested IP address or empty if it
+     *     is not in the DB.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -97,7 +98,7 @@ IpRiskResponse ipRisk(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoIP IP Risk database.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return an IPRiskResponse for the requested IP address or empty if it is not in the DB.
+     * @return an IpRiskResponse for the requested IP address or empty if it is not in the DB.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -108,7 +109,7 @@ Optional<IpRiskResponse> tryIpRisk(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoLite ASN database.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return an IspResponse for the requested IP address.
+     * @return an AsnResponse for the requested IP address.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -119,7 +120,7 @@ AsnResponse asn(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoLite ASN database.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return an IspResponse for the requested IP address or empty if it is not in the DB.
+     * @return an AsnResponse for the requested IP address or empty if it is not in the DB.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -130,7 +131,7 @@ Optional<AsnResponse> tryAsn(InetAddress ipAddress) throws IOException,
      * Look up an IP address in a GeoIP Connection Type database.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return a ConnectTypeResponse for the requested IP address.
+     * @return a ConnectionTypeResponse for the requested IP address.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -141,7 +142,8 @@ ConnectionTypeResponse connectionType(InetAddress ipAddress)
      * Look up an IP address in a GeoIP Connection Type database.
      *
      * @param ipAddress IPv4 or IPv6 address to lookup.
-     * @return a ConnectTypeResponse for the requested IP address or empty if it is not in the DB.
+     * @return a ConnectionTypeResponse for the requested IP address or empty if it
+     *     is not in the DB.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */
@@ -206,8 +208,8 @@ IspResponse isp(InetAddress ipAddress) throws IOException,
     /**
      * Look up an IP address in a GeoIP ISP database.
      *
-     * @param ipAddress IPv4 or IPv6 address to look up or empty if it is not in the DB.
-     * @return an IspResponse for the requested IP address.
+     * @param ipAddress IPv4 or IPv6 address to look up.
+     * @return an IspResponse for the requested IP address or empty if it is not in the DB.
      * @throws com.maxmind.geoip2.exception.GeoIp2Exception if there is an error looking up the IP
      * @throws java.io.IOException                          if there is an IO error
      */