TP 3 Draft Specs

This issue is a central hub for the specifications of TP 3. It can refer to more detailed issues but should offer a summary of the features we plan for the next major release of TP.

Releasable singletons

We should release all internal providers under memory pressure, but not automatically as some can’t recover their state. Thus, users should have full control over this. We should provide different mechanisms to let user mark classes whose singletons can be released:

• add an annotation @Releasable that can apply to a type that is injected
• add .markAsReleasable() to the bindings API

Details in #212

Better scope annotations

For now, only “singleton classes” can be annotated to indicate in which scope TP should create an instance of theses classes. We want to extend this mechanism, which actually breaks the JSR 330, and allows things like:

@ActivityScope 
public class Foo {}

Which means Foo can only be created by TP inside a scope that supports the @ActivityScope, but without Foo being a singleton. A singleton would be expressed by:

@ActivityScope  @Singleton
public class FooSingleton {}

Note that this new notation is just making more clear and distinct to which scope entities belong and how they are recycled. These 2 concepts are currently entangled in JSR 330. Also, using the new annotation model will still preserve the strong contract of

@Singleton
public class FooSingleton {}

being a singleton of the root scope, as everyone would expect.

This change should not require any binding API changes.

Better TP API

Changing the API will also help users to be sure of which TP version they are using and avoid misinterpreting the new annotation model.

• Toothpick.inject(foo, scope) --> scope.inject(foo), more details in #217.
• give scopes a fluent API, more details in #218.
• change bind --> support for scope annotation, more details in #169
• allow to inject package-protected classes, right now we only allow public #227 (testEmptyConstructor_shouldWork_whenConstructorIsProtected)
• allow @Inject annotated methods to send Exceptions, more details in #200
• ~give a base class to factories and MemberInjectors? to limit the generated code size~ (#347).

Improve Examples

• Fix Test examples by using ToothpickRule
• Add a @Singleton example
• Add Presenter and Flow example (state preservation)
• Improve coding style in examples -> inner classes, bad names, …
• Make sure all examples work (https://github.com/stephanenicolas/toothpick/issues/337)

KTP

https://github.com/stephanenicolas/toothpick/issues/316

Documentation

• Improve documentation and come with a way to represent the way it works internally for maintainers.

Misc

• Add test to make sure that releasable is working
• Add test to verify that the new scope and singleton system works
• Add tests to make sure that the whole library works for Kotlin
• Add support for Mockk (https://github.com/stephanenicolas/toothpick/issues/334)
• ~Being able to test scope graph at build time using unit tests~ (#348)
• switch to Mockito internally
• make scopes lifecycle-aware (https://github.com/stephanenicolas/toothpick/issues/332)

other ideas

Add an annotation @ShouldBeLazy so that a class can only be injected lazily. This could help for instance to delay the creation of some network related classes…

[ultimate-deej]

Let me share my thoughts on it.

1. Releasable singletons.

   tldr: I doubt this is something a DI library should do.

   Detailed explanation I’m strongly against this. This will introduce more complexity with little to no benefits. If user needs to handle low memory conditions they should do it solely on their own without resorting to a DI library. After all, Toothpick is a dependency injection library, not a memory management library. Finally, this will make singletons not so singletons.

2. Better scope annotations. Love it! Will definitely give more control and make things clearer. As for JSR 330, I don’t think it will break the standard (emphasis mine):

   If a scope annotation is present, the injector may retain the instance for possible reuse in a later injection

   However, it might in fact cause confusion to users.

3. The rest looks 👍, except that it is unclear to me what #169 is about

[stephanenicolas]

Ticket closed as all was released in 3.0.0