See which other JDK subtypes of `AutoCloseable` should be `@MustCall("close")`

[msridhar]

Right now, our JDK model does not annotate AutoCloseable as @MustCall("close"):

https://github.com/typetools/jdk/blob/88af971354b7e482ade8b250fde7699ed2e20217/src/java.base/share/classes/java/lang/AutoCloseable.java#L56-L59

It'd be nice if we could annotate it as @MustCall("close") and then annotate those AutoCloseable types that do not manage a resource as @MustCall(""), but it seems this causes issues with excessive warnings. Perhaps we could fix this? If not, we should at some point look through the list of JDK types implementing AutoCloseable and see which other ones should be @MustCall("close"):

https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/AutoCloseable.html

[Tejasker]

hey @msridhar ,I guess you are correct like annotating @MustCall("close") would lead to excessive warnings especially for classes that don't manage any resources and one cannot determine the appropriate warnings in the stack.

[jakelurie]

Can someone help verify if I understand this problem correctly:
We want to look through all JDK types implementing AutoCloseable and check if they manage resources or not, and tag them all with @MustCall("") for non resource managing types and @MustCall("close") for resource managing types.

I looked through the application and only see the following classes defined within the application implementing AutoCloseable:

• CloseableAndMore on CloseableAndMore.java:11
• StaticNested on ScopingConstruct.java:8
• NestedNested on ScopingConstruct.java:12
• NestedInner on ScopingConstruct.java:17
• Inner on ScopingConstruct.java:23
• InnerInner on ScopingConstruct.java:30
• InitalizationAfterSuperTest on InitalizationAfterSuperTest.java:12

But all of these look like test related objects. These are not the lines that we want to annotate, right?

I began looking further to see if any imported packages implement AutoCloseable, and found the following two objects within the app src code that do implement AutoCloseable:

• Context
• FileLock

But the object classes are not defined within this project, so they cannot be annotated.
Is the ask here to simply annotate these test objects? All of which appear to be non-resource managing.
Or is it to wrap the Context and FileLock objects in the source code with 'try with resources' blocks to ensure the .close() is called for these resource manging types?

[jakelurie]

@msridhar @Tejasker

[msridhar]

Thanks for looking into this, @jakelurie! I don't think you've quite understood the issue correctly. Take a look at this page:

https://docs.oracle.com/en/java/javase/17/docs//api/java.base/java/lang/AutoCloseable.html

At the top of the page, you can see a list of all types within the JDK that implement AutoCloseable. The idea would be to go through that list, figure out which of the types actually manage a resource, and add an @InheritableMustCall("close") annotation to those types in the typetools/jdk repository, which will cause those types to be modeled as resources by the Resource Leak Checker. Does that make sense?

[parameshn]

After reviewing the JDK APIs, I identified the following categories of AutoCloseable types that own OS or native resources and therefore must be closed. These types should be annotated with @InheritableMustCall("close") so the Resource Leak Checker models them correctly.

1. File I/O (15 types)

I identified classes such as:

FileInputStream
FileOutputStream
RandomAccessFile
FileChannel
AsynchronousFileChannel
FileLock
FileSystem
FileImageInputStream / FileImageOutputStream
FileCacheImageInputStream / FileCacheImageOutputStream
JarFile
ZipFile
FileReader
FileWriter

These classes open real files or file descriptors.
The JDK documentation explicitly states that calling close() releases system resources (for example, FileInputStream.close() and FileOutputStream.close()).
Because they directly own file descriptors, they must be closed to avoid OS-level resource leaks.

2. Network I/O (16 types)

I identified the following network-related classes:

Socket, ServerSocket, DatagramSocket, MulticastSocket
SSLSocket, SSLServerSocket
SocketChannel, ServerSocketChannel, DatagramChannel
AsynchronousSocketChannel, AsynchronousServerSocketChannel
SCTP channels (SctpChannel, SctpServerChannel, SctpMultiChannel)

These classes manage native OS network sockets.
I also included HTTP server types:

HttpExchange
HttpsExchange

Calling close() on these types releases the underlying socket or terminates the TCP connection.
Since they own native network handles, they must be closed.

3. JDBC / Database (12 types)

I identified the following JDBC-related interfaces:

Connection
Statement, PreparedStatement, CallableStatement
ResultSet
RowSet
CachedRowSet, FilteredRowSet, JdbcRowSet, JoinRowSet, WebRowSet
SyncResolver

These types manage database connections, cursors, or other native DB resources.
They are listed in the JDK documentation as AutoCloseable.
Closing them is required to release database and network resources.

4. NIO Infrastructure (6 types)

I identified the following NIO infrastructure classes:

Selector
AbstractSelector
WatchService
DirectoryStream
SecureDirectoryStream
ModuleReader

These types rely on OS-level facilities such as selectors, file system watches, or directory handles.
All of them implement AutoCloseable and must be closed to free native resources.

5. JMX / RMI (8 types)

I identified the following management and RMI-related types:

JMXConnector
RMIConnection
RMIConnector
RMIConnectionImpl
RMIServerImpl
RMIJRMPServerImpl
RMIIIOPServerImpl (historical)

These types open network connections, listen on ports, or manage threads.
They implement AutoCloseable and should be explicitly closed.

6. Image I/O (4 types)

I identified the following Image I/O types:

ImageInputStream
ImageOutputStream
ImageInputStreamImpl
ImageOutputStreamImpl

File-backed implementations such as FileCacheImageInputStream and FileCacheImageOutputStream rely on real files.
These classes must be closed to release underlying file or native resources.
Memory-only image streams are wrappers and are not included.

7. Audio (15 types)

I identified the following audio and MIDI-related types:

Mixer
Line, DataLine, Clip, Port
SourceDataLine, TargetDataLine
AudioInputStream
MidiDevice
MidiDeviceReceiver, MidiDeviceTransmitter
Receiver, Transmitter
Sequencer, Synthesizer

These types often open native audio or MIDI hardware resources.
Calling close() releases those underlying system resources.

8. JDK Flight Recorder (5 types)

I identified the following JFR-related types:

Recording
RecordingFile
RecordingStream
RemoteRecordingStream
EventStream

These classes manage file or network resources used for recording events.
They implement AutoCloseable and must be closed.

9. JShell Execution (8 types)

I identified the following JShell-related types:

ExecutionControl
DirectExecutionControl
JdiDefaultExecutionControl
JdiExecutionControl
LocalExecutionControl
RemoteExecutionControl
StreamingExecutionControl
JShell

These types may hold native processes or debugging connections.
They must be closed to ensure proper cleanup.

10. ClassLoaders (3 types)

I identified the following class loaders:

URLClassLoader
MLet
PrivateMLet

These classes load JAR files and may hold open file handles or lock JARs on disk.
Closing them is required to release those resources.

11. Native Memory (1 type)

I identified:

ResourceScope (from jdk.incubator.foreign)

This type represents a scoped region of native memory.

It implements AutoCloseable specifically to free native resources when closed.

Does this list of AutoCloseable types that own OS/native resources look complete and correct, or are there any additions/removals you would suggest before I start submitting PRs for missing @InheritableMustCall("close") annotations?

[msridhar]

@parameshn thanks for this! In our context, any type that implements java.io.Closeable will already be @InheritableMustCall("close"), see here. So for this issue, we only care about other types. So, if you restrict your list to such types, that seems reasonable to me and a clear improvement over what we have.

Have you looked at Java 2D and other GUI code? They have a dispose method that I guess may release some system resources. Should they be on the list?

To go further, you'd need to open a pull request on the typetools/jdk repo to add the relevant @InheritableMustCall annotations.

[parameshn]

Java 2D / GUI APIs (dispose())

I looked into Java 2D / GUI types with dispose() (for example Graphics,
Window, and BufferStrategy). While dispose() does release native
resources, these types do not implement AutoCloseable, and their
lifecycles are typically managed by the GUI framework or event system
rather than by lexical scope.

In practice, enforcing dispose() via the MustCall checker would likely
introduce a large number of false positives, especially in common
Swing painting and window management patterns.

Conclusion: These APIs are out of scope for the current issue,
which is focused on AutoCloseable + close().

---

Next steps

• I’ll restrict the scope to AutoCloseable types that do not implement
  java.io.Closeable
• I’ll start opening small, focused PRs to add
  @InheritableMustCall("close") where appropriate
• Each PR will reference this issue for context

Please let me know if you’d prefer a different grouping strategy or if there
are any types you’d like me to include or exclude before I begin.

[msridhar]

@parameshn to me it looks like you are copy-pasting your responses from an LLM like ChatGPT. If so, I feel it would be best if you were open about that.

I don't understand the point about dispose(). Do you have examples showing why it would lead to false positives?

[parameshn]

I’m mainly relying on official documentation, educational resources, and reputable blogs for the technical content. I sometimes use tools to help with text formatting, structuring explanations, or handling more mundane writing tasks, but the understanding and references come from the source material itself. I’m happy to be transparent about that.

Why calling dispose() leads to false positives

The JDK documentation for java.awt.Graphics.dispose() states:

For efficiency, programmers should call dispose when finished using a Graphics object only if it was created directly from a component or another Graphics object.

Source:
https://docs.oracle.com/javase/8/docs/api/java/awt/Graphics.html#dispose--

So we have to call dispose() only when we own the Graphics instance.

User-owned Graphics (dispose required)

Here is an example and discussion of that scenario:

public class Main {
    public static void main(String[] args) {
        BufferedImage img = get();
        Graphics g = img.getGraphics();

        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        try {
            ImageIO.write(img, "jpg", baos);
            baos.flush();
            byte[] imageInByte = baos.toByteArray();
            baos.close();
            Files.write(Paths.get("test2.png"), imageInByte);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    public static BufferedImage get() {
        BufferedImage res =
            new BufferedImage(50, 50, BufferedImage.TYPE_INT_ARGB);

        Graphics g = res.getGraphics();
        g.drawRect(0, 0, 20, 20);
        g.dispose();
        g.drawOval(5, 5, 5, 5); // this statement won't work

        return res;
    }
}

From:
#https://stackoverflow.com/questions/29274189/should-i-explicitly-dispose-the-graphics-object

In this case, the Graphics object is obtained via java.awt.image.BufferedImage.getGraphics(), so the caller owns the underlying native resources and must call dispose().

Framework-owned Graphics (dispose must NOT be called)

Graphics objects are also created and passed by the client-side framework (e.g., Swing painting via paint / paintComponent). Calling dispose() on these does not work as intended.

Example:

@Override
protected void paintComponent(Graphics grphcs) {
    super.paintComponent(grphcs);

    Graphics2D g2d = (Graphics2D) grphcs;
    g2d.drawImage(background, 0, 0, null);

    // g2d.dispose(); // if I uncomment this no labels will be shown
}

Explanation from the discussion:

The thing is that the Graphics context you are using in paintComponent is created and provided by the caller (the framework), which is also responsible for disposing of it.

You only need to dispose of Graphics when you actually create it yourself (for example by calling Component.getGraphics()). In your case, you're not creating it, you're just casting it, so do not call dispose in this case.

From:
#https://stackoverflow.com/questions/13911743/why-does-calling-dispose-on-graphics-object-cause-jpanel-to-not-render-any-com

Why @MustCall("dispose") causes false positives

If we annotate:

@InheritableMustCall("dispose")
abstract class Graphics { }

then every Graphics instance must be disposed.

However, Graphics objects provided by the framework must not be disposed by user code. Since the checker cannot distinguish:

• framework-owned Graphics (must not dispose)
• user-owned Graphics (must dispose)

using Java’s type system alone, this annotation would:

• produce warnings in essentially all Swing/AWT painting code
• encourage incorrect calls to dispose()
• flag correct code as leaking resources

These are false positives, caused by the fact that ownership and lifecycle of Graphics objects are contextual and framework-managed, not lexically scoped.

Curious to hear your thoughts on this, and happy to revise if I’m missing something.
I’d welcome guidance on how you recommend handling this ownership distinction in practice, or if there’s an established pattern I should follow here.

[parameshn]

Scope reduction after accounting for Closeable

Since java.io.Closeable is already annotated with @MustCall("close"), I reduced my initial list of ~93 AutoCloseable types to a much smaller and more focused subset that is not already covered transitively.

Below are the categories and rationale for the remaining types.

JDBC / Database types

Type structure

ResultSet ← CONNECTED (owns DB cursor)
└─ RowSet (extends ResultSet)

javax.sql.rowset
├─ JdbcRowSet ← CONNECTED RowSet
│ └─ extends RowSet
│
├─ CachedRowSet ← DISCONNECTED RowSet
│ └─ extends RowSet
│
├─ FilteredRowSet ← DISCONNECTED
│ └─ extends CachedRowSet
│
├─ WebRowSet ← DISCONNECTED
│ └─ extends CachedRowSet
│
└─ JoinRowSet ← DISCONNECTED
└─ extends WebRowSet

Connected types clearly manage live database resources (connections, cursors) and must be closed.
Although disconnected RowSet implementations are not tied to an active connection, they should still be closed.

Why disconnected RowSets should be closed

Disconnected means there is no connection issue to close, so you can leave it.
However, I think it's a good practice to always close what you open and not leave it to the GC.
Given a large enough server with many requests, if it causes open file descriptors, it can eventually be an issue.

From
https://stackoverflow.com/questions/12278351/should-i-always-close-a-cachedrowset-even-if-it-goes-out-of-scope

When working with CachedRowSet instances in Java, it is vital to understand resource management practices to prevent potential memory leaks and ensure optimal application performance. Explicitly closing these instances helps maintain application efficiency and reliability.

From
https://codingtechroom.com/question/should-i-always-close-cachedrowset-even-if-it-goes-out-of-scope

Example

CachedRowSet rowset = RowSetProvider.newFactory().createCachedRowSet();
rowset.execute(conn);
// use rowset
rowset.close();

Audio types (javax.sound.sampled)

Type structure
javax.sound.sampled
├─ Mixer (interface)
│
├─ Line (interface)
│ ├─ DataLine (interface)
│ │ ├─ SourceDataLine (interface)
│ │ └─ TargetDataLine (interface)
│ │
│ ├─ Clip (interface)
│ └─ Port (interface)

Closes the line, indicating that any system resources in use by the line can be released.

From
https://docs.oracle.com/en/java/javase/23/docs/api/java.desktop/javax/sound/sampled/Line.html#close()

Why audio lines must be closed

Lines hold native audio resources (mixers, buffers, device handles)

Leaving them open can:

• leak memory
• block threads (e.g. drain())
• stall capture or playback

Subinterfaces (SourceDataLine, TargetDataLine, Clip) extend Line, so failing to close them violates the lifecycle contract

You need to close the clip to free any resources used by it. If you don't you will leak memory and eventually crash with an OutOfMemoryException.

From
https://stackoverflow.com/questions/21549815/why-is-it-necessary-to-close-an-audio-clip

MIDI types (javax.sound.midi)

Package structure
javax.sound.midi
├─ MidiDevice (interface)
│ ├─ Sequencer (interface)
│ └─ Synthesizer (interface)
│
├─ Receiver (interface)
└─ Transmitter (interface)
├─ MidiDeviceReceiver
└─ MidiDeviceTransmitter

MIDI resource ownership

MIDI types typically manage native or system-level resources, including:

• MIDI hardware devices
• Native MIDI/audio drivers
• Background threads for event delivery
• OS-level ports, buffers, and timing resources

These resources are limited and shared across applications, so explicit closure is required.

Why these types should be closed

If an application opens a MidiDevice explicitly, it has to close it explicitly to free system resources and enable the application to exit cleanly.

From
https://docs.oracle.com/en/java/javase/23/docs/api/java.desktop/javax/sound/midi/MidiDevice.html

Closing a MidiDevice:

• releases native MIDI resources
• stops internal threads
• automatically closes all associated transmitters and receivers
• Receiver and Transmitter

Indicates that the application has finished using the receiver, and that limited resources it requires may be released or made available.

From
https://docs.oracle.com/en/java/javase/23/docs/api/java.desktop/javax/sound/midi/Receiver.html

Allocate native buffers and event queues
Leaving them open can keep devices active indefinitely
Implement AutoCloseable specifically to enforce lifecycle management
MidiDeviceReceiver and MidiDeviceTransmitter
Device-bound implementations of Receiver and Transmitter
Directly tied to a specific MidiDevice
Must be closed to fully release device-level resources

Sequencer

A hardware or software device that plays back a MIDI sequence is known as a sequencer.

From
https://docs.oracle.com/en/java/javase/23/docs/api/java.desktop/javax/sound/midi/Sequencer.html

Sequencers open MIDI devices
Allocate timing and scheduling threads
Maintain internal event buffers

Must be closed when finished

Reference:
https://devtut.github.io/java/audio.html#play-a-midi-file

Synthesizer

Converts MIDI events into audio output

Opens audio output lines, soundbanks, and native mixing resources

Leaving it open can:

• leak memory
• lock audio devices
• prevent clean JVM shutdown

JShell execution types (needs further research)

These types extend AutoCloseable and appear to manage execution environments, processes, or JDI connections, but I need to investigate them further due to limited public documentation.

jdk.jshell.spi
└─ ExecutionControl (SPI interface)

jdk.jshell.execution
├─ DirectExecutionControl
├─ LocalExecutionControl
├─ RemoteExecutionControl
├─ StreamingExecutionControl
├─ JdiExecutionControl
└─ JdiDefaultExecutionControl

I’d really appreciate your opinion on this scope reduction and whether the reasoning looks sound.
Could you also share any guidance on gaps or improvements you’d recommend?

[msridhar]

@parameshn the scope reduction sounds good. I'd suggest you go ahead and open PRs on the typetools/jdk repo. I'd do separate PRs based on your exact grouping (JDBC, audio, etc.). We can go over each separate PR more carefully. Thanks for the investigation!

[parameshn]

Thanks for the confirmation

I’ll start with the JDBC-related types and then move on to audio/MIDI, since the lifecycle contracts there are the clearest and best-documented. Looking forward to feedback on each PR as they come in