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 all 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
2 changes: 1 addition & 1 deletion lychee.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
104 changes: 49 additions & 55 deletions mise.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

24 changes: 13 additions & 11 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 @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand Down Expand Up @@ -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.

@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 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
Loading
Loading