diff --git a/README.md b/README.md index e7fedb23b..9aab8b7c2 100644 --- a/README.md +++ b/README.md @@ -45,29 +45,29 @@ dependencies { // Set up your dagger dependencies and compiler // Include this in kotlin or android modules - implementation("se.ansman.dagger.auto:core:0.9.1") - kapt("se.ansman.dagger.auto:compiler:0.9.1") + implementation("se.ansman.dagger.auto:core:0.10.0") + kapt("se.ansman.dagger.auto:compiler:0.10.0") // If you're using KSP - ksp("se.ansman.dagger.auto:compiler:0.9.1") + ksp("se.ansman.dagger.auto:compiler:0.10.0") // Include this only in android modules - implementation("se.ansman.dagger.auto:android:0.9.1") + implementation("se.ansman.dagger.auto:android:0.10.0") // Add these if you want to replace objects during tests - testImplementation("se.ansman.dagger.auto:android-testing:0.9.1") - kaptTest("se.ansman.dagger.auto:compiler:0.9.1") + testImplementation("se.ansman.dagger.auto:android-testing:0.10.0") + kaptTest("se.ansman.dagger.auto:compiler:0.10.0") // If you're using KSP - kspTest("se.ansman.dagger.auto:compiler:0.9.1") + kspTest("se.ansman.dagger.auto:compiler:0.10.0") // If you want to provide Retrofit services add the Retrofit dependency - implementation("se.ansman.dagger.auto:retrofit:0.9.1") + implementation("se.ansman.dagger.auto:retrofit:0.10.0") // If you want to inject a CoroutineScope into ViewModels add the ViewModel dependency - implementation("se.ansman.dagger.auto:androidx-viewmodel:0.9.1") + implementation("se.ansman.dagger.auto:androidx-viewmodel:0.10.0") // If you want to automatically provide your Room DAOs add the Room dependency - implementation("se.ansman.dagger.auto:androidx-room:0.9.1") + implementation("se.ansman.dagger.auto:androidx-room:0.10.0") } ``` diff --git a/gradle.properties b/gradle.properties index a06385f51..9a03d9ead 100644 --- a/gradle.properties +++ b/gradle.properties @@ -11,5 +11,5 @@ kapt.include.compile.classpath=false android.useAndroidX=true -version=0.10.0-SNAPSHOT -latestRelease=0.9.1 +version=0.10.0 +latestRelease=0.10.0 diff --git a/src/doc/dokka/0.10.0/android/index.html b/src/doc/dokka/0.10.0/android/index.html new file mode 100644 index 000000000..06559bd54 --- /dev/null +++ b/src/doc/dokka/0.10.0/android/index.html @@ -0,0 +1,96 @@ + + +
+ +An Initializer that will initialize a Singleton scoped AutoDaggerStartupInitializer.
This will be called by androidx.startup, provides no result and has no dependencies.
0.2
An Initializer that will initialize a Singleton scoped AutoDaggerStartupInitializer.
Denotes that the class referenced using type is to be replaced by this type.
The type to replace must be annotated with AutoBind. Any qualifiers and binding keys will be copied from the referenced type.
The annotated class must implement the types which are bound by the referenced type.
If the replaced type uses multibindings (AutoBindIntoSet or AutoBindIntoMap) then those are only replaced if the annotated type also implements them. Otherwise the multibinding is removed
So for example. If the target type uses @AutoBindIntoSet
to bind it as a Closeable
but your replacement doesn't implement Closeable
then that binding is removed. If it does implement Closeable
then the binding is replaced with the fake binding.
Normally the replacement object needs to be provided to the dependency graph using either an @Provides
annotated method or using an @Inject
annotated constructor.
Auto Dagger allows you to annotate a Kotlin object with @Replaces
without it being provided in the graph. This is especially useful for tests:
@Replaces(ThreadPoolExecutor::class)
object DirectExecutor : Executor {
override fun execute(command: Runnable) {
command.run()
}
}
If the target type is annotated with AutoInitialize, then an empty module will be generated to replace the auto initialize module, effectively disabling it.
// In your `main` source set
interface Repository
@AutoBind(asTypes = [Repository::class])
@AutoBindIntoSet(asTypes = [Closeable::class])
@Singleton
class RealRepository @Inject constructor() : Repository, Closeable {
override fun close() {}
}
// In your `test` source set
// Since `FakeRepository` doesn't implement `Closeable` then it's
// not bound as `Closable` and the real `RealRepository -> Closeable`
// binding is removed.
@Replaces(RealRepository::class)
class FakeRepository @Inject constructor() : Repository
0.3
The component to provide the DAOs in. Defaults to SingletonComponent.
A marker for Room Databases that will automatically contribute all DAOs in your database to the dependency graph.
Simply add this annotation to a Database and auto-data will provide all DAOs.
Example:
@AutoProvideDaos
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
abstract fun userDao(): UserDao
}
// You'll also need to provide the Database instance to the component you want to inject the service into:
@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {
@Provides
@Singleton
fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
Room.databaseBuilder(context, AppDatabase::class.java, "database-name").build()
}
By default, the DAOs are provided in the SingletonComponent. If you'd like to change this you can do so by specifying the inComponent
parameter:
@AutoProvideDaos
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
abstract fun userDao(): UserDao
}
The component to provide the DAOs in. Defaults to SingletonComponent.
A marker for Room Databases that will automatically contribute all DAOs in your database to the dependency graph.
A Dagger module which provides a CoroutineScope that is tied to the lifecycle of a ViewModel.
The provided scope is qualified with ViewModelSpecific and will be canceled when the viewmodel is cleared and it ses a SupervisorJob and the [Dispatchers].Main.immediate
dispatcher.
To inject:
@HiltViewModel
class MyViewModel @Inject constructor(
@ViewModelSpecific
private val viewModelScope: CoroutineScope
) : ViewModel()
A qualifier indicating that the annotated type is tied to ViewModelComponent.
By default the following things are automatically provided:
A CoroutineScope that is tied to the view model's lifecycle is contributed. The scope uses a SupervisorJob and the [Dispatchers].Main.immediate
dispatcher.
To use it simply inject it like this:
@HiltViewMode
class MyViewModel @Inject constructor(
@ViewModelSpecific
private val viewModelScope: CoroutineScope
) : ViewModel()
A Dagger module which provides a CoroutineScope that is tied to the lifecycle of a ViewModel.
A qualifier indicating that the annotated type is tied to ViewModelComponent.
Specifies how generic supertypes should be bound. Defaults to BindGenericAs.ExactType or if the target type is annotated with BindGenericAs.Default.
Which component to install the binding in. Defaults to being inferred based on the scope.
A version of AutoBind that binds the object using IntoMap. The object must also be annotated with a MapKey annotated annotation such as StringKey, MapKey, or a custom annotation.
For more documentation on auto bind see AutoBind.
See also https://dagger.dev/dev-guide/multibindings.html#map-multibindings
0.2
Which component to install the binding in. Defaults to being inferred based on the scope.
Specifies which supertypes to bind the object as. Required if there are multiple supertypes.
Specifies how generic supertypes should be bound. Defaults to BindGenericAs.ExactType or if the target type is annotated with BindGenericAs.Default.
Specifies how generic supertypes should be bound. Defaults to BindGenericAs.ExactType or if the target type is annotated with BindGenericAs.Default.
Which component to install the binding in. Defaults to being inferred based on the scope.
A version of AutoBind that binds the object using IntoSet.
For more documentation on auto bind see AutoBind.
See also Set Multibindings
0.2
Which component to install the binding in. Defaults to being inferred based on the scope.
Specifies which supertypes to bind the object as. Required if there are multiple supertypes.
Specifies how generic supertypes should be bound. Defaults to BindGenericAs.ExactType or if the target type is annotated with BindGenericAs.Default.
Which component to install the binding in. Defaults to being inferred based on the scope.
Instructs Auto Dagger to automatically bind the annotated type as its parent type.
To use this annotation the class must:
Not be generic - To bind generic types implement your own binding that provides the type arguments.
Have exactly one direct supertype - If you have multiple supertypes then specify which to bind using asTypes.
Only direct supertypes can be bound. For example, if your class implements Closeable
you cannot bind it as AutoCloseable
(which is a supertype of Closeable
). To work around this, add the bound type as an explicit supertype.
interface Repository
@AutoBind
@Singleton
class RealRepository @Inject constructor() : Repository
// Generates the equivalent to:
@Binds
abstract fun RealRepository.bindRealRepositoryAsRepository(): Repository
Auto Dagger tries to infer the component based on the scope of the object using the following mapping:
Scope | Component |
---|---|
No scope | SingletonComponent |
Singleton | SingletonComponent |
Reusable | SingletonComponent |
ActivityRetainedScoped | ActivityRetainedComponent |
ActivityScoped | ActivityComponent |
FragmentScoped | FragmentComponent |
ServiceScoped | ServiceComponent |
ViewScoped | ViewComponent |
ViewModelScoped | ViewModelComponent |
ViewWithFragmentScoped | ViewWithFragmentComponent |
If you want to install the binding in a different component or if you're using a custom scope, then you can use the inComponent parameter to explicit provide the component.
If you have multiple supertypes use the asTypes parameter to specify which of them to bind. You only need to specify the raw class name if the type is generic (i.e. if your type implements Callable<Stuff>
you pass asTypes = [Callable::class]
to indicate you want to bind it).
Normally the bound object needs to be provided to the dependency graph using either an @Provides
annotated method or using an @Inject
annotated constructor.
Auto Dagger allows you to annotate a Kotlin object with @AutoBind
without it being provided in the graph. This is especially useful for tests:
@AutoBind
object DirectExecutor : Executor {
override fun execute(command: Runnable) {
command.run()
}
}
To bind the object using multibinding, use AutoBindIntoSet and/or AutoBindIntoMap. These can be used at the same time as AutoBind.
Any Qualifiers on the annotated type will be carried over to the binding:
@Named("Prod")
@AutoBind
class ProdAuthenticator @Inject constructor() : Authenticator
// Generates the equivalent to:
@Binds @Named("Prod")
abstract fun ProdAuthenticator.bindProdAuthenticatorAsAuthenticator(): Authenticator
0.2
Which component to install the binding in. Defaults to being inferred based on the scope.
Specifies which supertypes to bind the object as. Required if there are multiple supertypes.
A class that can initialize multiple Initializable in order of their priority.
0.2
If the initializer has been initialized or not (i.e. if initialize has been called).
Initializes the provided Initializable. This method is thread safe and calling it multiple times will only initialize the initializables once.
Returns a new Initializable with the given priority.
Initializes the provided Initializable. This method is thread safe and calling it multiple times will only initialize the initializables once.
If any initializable throws an exception the remaining initializes are still initialized before rethrowing the exception. If multiple initializables throw then the first one is thrown with the other exceptions added as suppressed exceptions.
If this method fails, calling it again will complete successfully without attempting to initialize the failed initializables again.
If the initializer has been initialized or not (i.e. if initialize has been called).
Marks the given objects as being initializable.
This will instruct Auto Dagger to provide the object as an Initializable which allows you to use AutoDaggerInitializer to later initialize the annotated objects.
If the object implements the Initializable interface then it will be created when AutoDaggerInitializer is injected and Initializable.initialize will be called when AutoDaggerInitializer.initialize is called.
Otherwise, the object is only created when AutoDaggerInitializer.initialize is called.
0.2
Specifies the default AutoBindIntoSet.bindGenericAs and AutoBindIntoMap.bindGenericAs for the annotated type.
This is useful if you know that the generic is always unique or if it's always shared. For example, an Interceptor<T>
should probably be bound as ExactType because you want to get all interceptors for a given type where as Resource<T>
should probably be bound as Wildcard since you're likely interested in getting all resources because there are no duplicates.
You can only add this to generic types.
Example when using wildcard:
@BindGenericAs.Default(BindGenericAs.Wildcard)
interface Resource<T> {
fun produce(): T
fun close()
}
@AutoBindIntoSet // Will bind this as Resource<*> instead of Resource<SomeThing>
class SomeResource @Inject constructor() : Resource<SomeThing> {
...
override fun close() { ... }
}
class ResourceCloser @Inject constructor(
val resources: Set<@JvmSuppressWildcards Resource<*>>
) {
fun closeAllResources() {
resources.forEach { it.close() }
}
}
Example when using exact type:
@BindGenericAs.Default(BindGenericAs.Type)
interface Interceptor<T> {
fun intercept(value: T): T
}
@AutoBindIntoSet // Will bind this as Interceptor<SomeThing>
class SomeInterceptor @Inject constructor() : Interceptor<SomeThing> {
...
}
class SomeOperation @Inject constructor(
val interceptors: Set<@JvmSuppressWildcards Interceptor<SomeThing>>
) {
fun performOperation(value: SomeThing): SomeThing {
return interceptors.fold(value) { v, interceptor -> interceptor.intercept(v) }
}
}
0.10.0
The type is bound as the exact supertype and as a wildcard type. For example, if the type is List<String>
then it's bound as both List<String>
and List<*>
.
The type is bound as a wildcard type. For example, if the type is List<String>
then it's bound as List<*>
.
Returns a representation of an immutable list of all enum entries, in the order they're declared.
This method may be used to iterate over the enum entries.
How generic types are bound when using multibinding such as AutoBindIntoSet or AutoBindIntoMap.
The default is ExactType unless the bound type is annotated with Default in which case that is used as the default.
0.6.0
Specifies the default AutoBindIntoSet.bindGenericAs and AutoBindIntoMap.bindGenericAs for the annotated type.
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
Returns an array containing the constants of this enum type, in the order they're declared.
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
if this enum type has no constant with the specified name
Returns an array containing the constants of this enum type, in the order they're declared.
This method may be used to iterate over the constants.
Converts the provided Lazy into an Initializable with the given priority (see AutoInitialize.priority).
When the returned Initializable is initialized, the lazy value is computed.
0.2
Converts the provided Lazy into an Initializable with the given priority (see AutoInitialize.priority).
Returns a new Initializable with the given priority.
Returns a new Initializable with the given priority.
0.2
An interface used to indicate that initialization isn't done when the object is created but rather when calling initialize.
This is useful if you want to be able to test your object.
Although you can use this interface by itself, it's meant to be used in conjunction with AutoInitialize.
0.2
Initializes the initializable.
Returns a new Initializable with the given priority.
Initializes the initializable.
A version of AutoBind that binds the object using IntoMap. The object must also be annotated with a MapKey annotated annotation such as StringKey, MapKey, or a custom annotation.
A version of AutoBind that binds the object using IntoSet.
A class that can initialize multiple Initializable in order of their priority.
Marks the given objects as being initializable.
How generic types are bound when using multibinding such as AutoBindIntoSet or AutoBindIntoMap.
An interface used to indicate that initialization isn't done when the object is created but rather when calling initialize.
The component to install the service in. Defaults to SingletonComponent.
Marks a Retrofit Service for automatic contribution to your dependency graph.
Simply add this annotation to the API services you want to inject and auto-dagger will generate the necessary modules.
Example:
@AutoProvideService
class ApiService {
@GET("users")
suspend fun getUsers(): List<User>
}
// You'll also need to provide a Retrofit instance to the component you want to inject the service into:
@Module
@InstallIn(SingletonComponent::class)
object RetrofitModule {
@Provides
@Singleton
fun provideRetrofit(): Retrofit = Retrofit.Builder()
.baseUrl("https://api.example.com/")
.addConverterFactory(SomeConverterFactory.create())
.build()
}
By default, services are installed in the SingletonComponent. If you'd like to change this you can do so by specifying the inComponent
parameter:
@AutoProvideService(inComponent = SomeOtherComponent::class)
class ApiService {}
If you have multiple retrofit instances and use qualifiers to differentiate them, you can specify the qualifier on the service:
@AutoProvideService
@Named("api1")
class ApiService {}
By default, provided service is unscoped and will be created every time it is injected. Retrofit caches the parsing of services so this is not an expensive operation, but it injected frequently you can avoid this by annotating your service with a scope or @Reusable
:
@Singleton // This must match the `inComponent` parameter of @AutoProvideService
@AutoProvideService
class ApiService {
// Service methods
}
// Or if you want to just make it reusable
@Reusable
@AutoProvideService
class ApiService {
// Service methods
}
The component to install the service in. Defaults to SingletonComponent.
Marks a Retrofit Service for automatic contribution to your dependency graph.