Skip to content

Clarify Windows memory-map file locking and fix Javadoc issues #733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
horgh merged 6 commits into from
Jun 30, 2026
Merged

Clarify Windows memory-map file locking and fix Javadoc issues #733

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
211330c
Clarify Windows memory map file locking
oschwald Jun 30, 2026
4c6d19c
Fix incorrect type names and descriptions in Javadoc
oschwald Jun 30, 2026
18371ee
Fix additional Javadoc errors found in audit
oschwald Jun 30, 2026
d56d6ba
Add missing optional-return note to tryIsp Javadoc
oschwald Jun 30, 2026
4db616f
Update mise deps
oschwald Jun 30, 2026
acdb7fd
Update lychee config for new version
oschwald Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ###
Expand Down
13 changes: 7 additions & 6 deletions src/main/java/com/maxmind/geoip2/DatabaseProvider.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,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
*/
Expand All @@ -108,7 +108,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
*/
Expand All @@ -119,7 +119,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
*/
Expand All @@ -130,7 +130,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
*/
Expand All @@ -141,7 +141,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
*/
Expand Down Expand Up @@ -206,7 +207,7 @@ 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.
* @param ipAddress IPv4 or IPv6 address to look up.

@gemini-code-assist gemini-code-assist Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While removing the misplaced "or empty if it is not in the DB" from the @param tag is correct, this phrase should be added to the @return tag on line 211 to maintain consistency with the other try* methods in this interface (such as tryCountry, tryCity, tryAsn, etc.) which return an Optional.\n\nCurrently, line 211 reads:\njava\n * @return an IspResponse for the requested IP address.\n\nIt should be updated to:\njava\n * @return an IspResponse for the requested IP address or empty if it is not in the DB.\n

* @return an IspResponse 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
Expand Down
20 changes: 11 additions & 9 deletions src/main/java/com/maxmind/geoip2/DatabaseReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,9 +214,9 @@ public Builder withCache(NodeCache cache) {
/**
* @param val The file mode used to open the GeoIP database
* @return Builder object
* @throws java.lang.IllegalArgumentException if you initialized the Builder with a URL,
* which uses {@link FileMode#MEMORY}, but you
* provided a different FileMode to this method.
* @throws java.lang.IllegalArgumentException if you initialized the Builder
* with an InputStream, which uses {@link FileMode#MEMORY}, but you
* provided a different FileMode to this method.
*/
public Builder fileMode(FileMode val) {
if (this.stream != null && FileMode.MEMORY != val) {
Expand Down Expand Up @@ -295,10 +295,12 @@ private <T> Optional<T> getResponse(
* </p>
* <p>
* If you are using {@code FileMode.MEMORY_MAPPED}, this will
* <em>not</em> unmap the underlying file due to a limitation in Java's
* {@code MappedByteBuffer}. It will however set the reference to
* the buffer to {@code null}, allowing the garbage collector to
* collect it.
* release this reader's reference to the mapped buffer, allowing the
* garbage collector to collect it when no other references remain. Java
* does not provide a supported way to unmap a
* {@code MappedByteBuffer} immediately. On Windows, this means the
* database file may remain unavailable for rename, replacement, or
* deletion until the mapped buffer is garbage collected.
* </p>
*
* @throws IOException if an I/O error occurs.
Expand Down Expand Up @@ -408,7 +410,7 @@ public Optional<AnonymousPlusResponse> tryAnonymousPlus(InetAddress ipAddress)
* Look up an IP address in a GeoIP IP Risk database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a IPRiskResponse for the requested IP address.
* @return an IpRiskResponse for the requested IP address.
* @throws GeoIp2Exception if there is an error looking up the IP
* @throws IOException if there is an IO error
*/
Expand Down Expand Up @@ -452,7 +454,7 @@ public 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 GeoIp2Exception if there is an error looking up the IP
* @throws IOException if there is an IO error
*/
Expand Down
Loading