How to migrate @Nullable provider method to jspecify

[leonardehrenfried]

Since we recently upgraded to Java 25 we wanted to migrate our project to jspecify and stop using javax.annotations.Nullable:

We have run into problems with our nullable provider methods, which look like this:

import dagger.Module;
import dagger.Provides;
import jakarta.inject.Singleton;
import javax.annotation.Nullable;
import org.opentripplanner.datastore.api.GoogleStorageDSRepository;
import org.opentripplanner.datastore.api.OtpDataStoreConfig;
import org.opentripplanner.datastore.base.DataSourceRepository;
import org.opentripplanner.framework.application.OTPFeature;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Module
public class GsDataSourceModule {

  private static final Logger LOG = LoggerFactory.getLogger(GsDataSourceModule.class);

  @Provides
  @Singleton
  @Nullable
  @GoogleStorageDSRepository
  DataSourceRepository provideGoogleStorageDataSourceRepository(OtpDataStoreConfig config) {
    if (OTPFeature.GoogleCloudStorage.isOff()) {
      return null;
    }
    return new GsDataSourceRepository(config.gsParameters());
  }
}

They cause runtime exceptions when I swap javax.annotation.Nullable with org.jspecify.annotations.Nullable:

java.lang.NullPointerException: Cannot return null from a non-@Nullable @Provides method
	at dagger.internal.Preconditions.checkNotNullFromProvides(Preconditions.java:64)
	at org.opentripplanner.ext.datastore.gs.GsDataSourceModule_ProvideGoogleStorageDataSourceRepositoryFactory.provideGoogleStorageDataSourceRepository(GsDataSourceModule_ProvideGoogleStorageDataSourceRepositoryFactory.java:52)
	at org.opentripplanner.ext.datastore.gs.GsDataSourceModule_ProvideGoogleStorageDataSourceRepositoryFactory.get(GsDataSourceModule_ProvideGoogleStorageDataSourceRepositoryFactory.java:42)
	at org.opentripplanner.ext.datastore.gs.GsDataSourceModule_ProvideGoogleStorageDataSourceRepositoryFactory.get(GsDataSourceModule_ProvideGoogleStorageDataSourceRepositoryFactory.java:13)
	at dagger.internal.DoubleCheck.getSynchronized(DoubleCheck.java:54)
	at dagger.internal.DoubleCheck.get(DoubleCheck.java:45)
	at org.opentripplanner.datastore.configure.DataStoreModule_ProvideDataStoreFactory.get(DataStoreModule_ProvideDataStoreFactory.java:51)
	at org.opentripplanner.datastore.configure.DataStoreModule_ProvideDataStoreFactory.get(DataStoreModule_ProvideDataStoreFactory.java:15)
	at dagger.internal.DoubleCheck.getSynchronized(DoubleCheck.java:54)
	at dagger.internal.DoubleCheck.get(DoubleCheck.java:45)
	at org.opentripplanner.graph_builder.GraphBuilderDataSources_Factory.get(GraphBuilderDataSources_Factory.java:50)
	at org.opentripplanner.graph_builder.GraphBuilderDataSources_Factory.get(GraphBuilderDataSources_Factory.java:14)
	at dagger.internal.DoubleCheck.getSynchronized(DoubleCheck.java:54)
	at dagger.internal.DoubleCheck.get(DoubleCheck.java:45)
	at org.opentripplanner.standalone.configure.DaggerLoadApplicationFactory$LoadApplicationFactoryImpl.graphBuilderDataSources(DaggerLoadApplicationFactory.java:225)
	at org.opentripplanner.standalone.configure.LoadApplication.validateConfigAndDataSources(LoadApplication.java:51)
	at org.opentripplanner.standalone.OTPMain.startOTPServer(OTPMain.java:120)
	at org.opentripplanner.standalone.OTPMain.main(OTPMain.java:55)

I debugged this with Claude and I found the suggestions not all that convincing.

Therefore I would like to hear it straight from the source: are Jspecify-Nullable-annotation provider methods supported or should I keep using javax.annotation.Nullable for that?

[Chang-Eric]

are Jspecify-Nullable-annotation provider methods supported

Currently, no, they are not. Dagger doesn't support Nullable type annotations today.

However, we should. We had previously looked into this and put it off due to a bug in the JDK. I looked into this now, and the issue we were worried about is fixed in JDK 17.0.19+ and JDK 21.0.8+ if using the flag -XDaddTypeAnnotationsToSymbol=true or by default in JDK 25. So I think we should be okay to move forward with adding this support to Dagger.

Likely I think we will release it behind a flag just to be safe so that users have to opt-in to it, so they can make sure they are using the correct JDK version with the addition configuration if necessary.