Skip to content

Add MustCall annotations to resource-owning JDBC, MIDI, and audio interfaces #254

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

Open
parameshn wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Add MustCall annotations to resource-owning JDBC, MIDI, and audio interfaces #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
473fc2e
Add Must call checker
parameshn Jan 16, 2026
e278dec
Add MustCall annotation to Line
parameshn Jan 21, 2026
b7542c4
Annote - Must call checker
parameshn Jan 21, 2026
62b0944
Annote - Must call checker
parameshn Jan 21, 2026
bb62832
Annote - Must call checker
parameshn Jan 21, 2026
eb6ecb7
Annote - Must call checker
parameshn Jan 22, 2026
050ad69
Annote - Must call checker
parameshn Jan 22, 2026
edd8992
Annote - Must call checker to JDBC Statement
parameshn Jan 28, 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
6 changes: 6 additions & 0 deletions src/java.desktop/share/classes/javax/sound/midi/MidiDevice.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@

import java.util.List;

import org.checkerframework.checker.mustcall.qual.InheritableMustCall;
import org.checkerframework.framework.qual.AnnotatedFor;


/**
* {@code MidiDevice} is the base interface for all MIDI devices. Common devices
* include synthesizers, sequencers, MIDI input ports, and MIDI output ports.
Expand Down Expand Up @@ -93,6 +97,8 @@
* @see Receiver
* @see Transmitter
*/
@AnnotatedFor({"mustcall"})
@InheritableMustCall("close")
Comment on lines +100 to +101
Copy link
Copy Markdown

@msridhar msridhar Jan 23, 2026

Choose a reason for hiding this comment

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

Based on the Javadoc, I think we may need @NotOwning annotations on methods like MidiSystem#getReceiver and MidiSystem#getTransmitter, to indicate that the MidiDevice returned by those APIs does not need to be explicitly closed. Do you agree?

Copy link
Copy Markdown
Author

@parameshn parameshn Jan 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

From my understanding, when MidiSystem.getReceiver() / getTransmitter() are used, the underlying MidiDevice is opened implicitly by the system and closed implicitly when the returned Receiver / Transmitter is closed (assuming no other Receivers/Transmitters remain open). As a result, the application does not own the MidiDevice; its responsibility is only to close the returned Receiver / Transmitter. Since the MidiDevice is not exposed by these APIs, there isn’t really a place to annotate it with @NotOwning at the API level.

// Requests a Receiver from the system.
// Implicitly opens the underlying MidiDevice
        Receiver receiver = MidiSystem.getReceiver();

// Closes the Receiver.
 // Implicitly closes the MidiDevice (if this was the last open one)
        receiver.close();

Copy link
Copy Markdown

@msridhar msridhar Feb 15, 2026

Choose a reason for hiding this comment

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

I think I misunderstood what was going on here. We don't need @NotOwning annotations on these APIs.

public interface MidiDevice extends AutoCloseable {

/**
Expand Down
5 changes: 5 additions & 0 deletions src/java.desktop/share/classes/javax/sound/midi/Receiver.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@

package javax.sound.midi;

import org.checkerframework.checker.mustcall.qual.InheritableMustCall;
import org.checkerframework.framework.qual.AnnotatedFor;

/**
* A {@code Receiver} receives {@link MidiEvent} objects and typically does
* something useful in response, such as interpreting them to generate sound or
Expand All @@ -36,6 +39,8 @@
* @see Synthesizer
* @see Transmitter
*/
@AnnotatedFor({"mustcall"})
@InheritableMustCall("close")
public interface Receiver extends AutoCloseable {

//$$fb 2002-04-12: fix for 4662090: Contradiction in Receiver specification
Expand Down
5 changes: 5 additions & 0 deletions src/java.desktop/share/classes/javax/sound/midi/Transmitter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@

package javax.sound.midi;

import org.checkerframework.checker.mustcall.qual.InheritableMustCall;
import org.checkerframework.framework.qual.AnnotatedFor;

/**
* A {@code Transmitter} sends {@link MidiEvent} objects to one or more
* {@link Receiver Receivers}. Common MIDI transmitters include sequencers and
Expand All @@ -33,6 +36,8 @@
* @author Kara Kytle
* @see Receiver
*/
@AnnotatedFor({"mustcall"})
@InheritableMustCall("close")
public interface Transmitter extends AutoCloseable {

/**
Expand Down
5 changes: 5 additions & 0 deletions src/java.desktop/share/classes/javax/sound/sampled/Line.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@

package javax.sound.sampled;

import org.checkerframework.checker.mustcall.qual.InheritableMustCall;
import org.checkerframework.framework.qual.AnnotatedFor;

/**
* The {@code Line} interface represents a mono or multi-channel audio feed. A
* line is an element of the digital audio "pipeline," such as a mixer, an input
Expand Down Expand Up @@ -66,6 +69,8 @@
* @see LineEvent
* @since 1.3
*/
@AnnotatedFor({"mustcall"})
@InheritableMustCall("close")
Copy link
Copy Markdown

@msridhar msridhar Jan 23, 2026

Choose a reason for hiding this comment

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

Is a Line object automatically open at the time it is constructed, is an explicit open() call required? If it's the latter, we might need to treat Line like Socket and add a @CreatesMustCallFor annotation somewhere. This might be tricky since Line is an interface.

Copy link
Copy Markdown
Author

@parameshn parameshn Jan 26, 2026

Choose a reason for hiding this comment

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

It’s the latter: a Line is not automatically open when obtained, and an explicit open() call is required.
Given that Line is an interface with multiple implementations and open(...) variants, annotating Line itself seems likely to be too coarse and incomplete. I think a similar argument applies to MidiDevice as well, since it is also an interface and can be opened both explicitly and implicitly. I’d appreciate your thoughts on whether there’s a better way to model this.

Copy link
Copy Markdown

@msridhar msridhar Feb 15, 2026

Choose a reason for hiding this comment

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

This is a bit tricky. I think ideally, we'd annotate any relevant methods that create an unopened Line as @MustCall({}), and then annotate any open methods that actually acquire the resource as @CreatesMustCallFor (like here). Does this seem infeasible?

Copy link
Copy Markdown
Author

@parameshn parameshn Feb 16, 2026

Choose a reason for hiding this comment

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

I think we need something like this for this instance

if method overrides another method:
    if overridden method has @InheritableCreatesMustCallFor:
        treat current method as if it has @CreatesMustCallFor

custom one maybe?

Copy link
Copy Markdown
Author

@parameshn parameshn Feb 21, 2026

Choose a reason for hiding this comment

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

@msridhar If that approach seems reasonable, I’m happy to prototype it and share a draft PR for feedback before applying it to Line and MidiDevice.

Copy link
Copy Markdown
Author

@parameshn parameshn Mar 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Hi
just checking in on this discussion.

Copy link
Copy Markdown

@msridhar msridhar Mar 11, 2026

Choose a reason for hiding this comment

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

Sorry @parameshn I've been very busy, hoping to get back to this next week

Copy link
Copy Markdown
Author

@parameshn parameshn Mar 11, 2026

Choose a reason for hiding this comment

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

No worries, thanks for the update! Looking forward to your thoughts.

public interface Line extends AutoCloseable {

/**
Expand Down
4 changes: 3 additions & 1 deletion src/java.sql/share/classes/java/sql/ResultSet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
package java.sql;

import org.checkerframework.checker.nullness.qual.Nullable;
import org.checkerframework.checker.mustcall.qual.InheritableMustCall;
import org.checkerframework.framework.qual.AnnotatedFor;

import java.math.BigDecimal;
Expand Down Expand Up @@ -149,7 +150,8 @@
* @since 1.1
*/

@AnnotatedFor("nullness")
@AnnotatedFor({"nullness", "mustcall"})
@InheritableMustCall("close")
public interface ResultSet extends Wrapper, AutoCloseable {

/**
Expand Down
5 changes: 5 additions & 0 deletions src/java.sql/share/classes/java/sql/Statement.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@
import org.checkerframework.checker.sqlquotes.qual.SqlEvenQuotes;
import org.checkerframework.checker.tainting.qual.Untainted;

import org.checkerframework.checker.mustcall.qual.InheritableMustCall;
import org.checkerframework.framework.qual.AnnotatedFor;

import java.util.regex.Pattern;
import static java.util.stream.Collectors.joining;

Expand All @@ -47,6 +50,8 @@
* @see ResultSet
* @since 1.1
*/
@AnnotatedFor({"mustcall"})
@InheritableMustCall("close")
public interface Statement extends Wrapper, AutoCloseable {

/**
Expand Down
Loading