Custom Scope Annotation

Purpose

Within the dependency injection framework used in this project, managing the lifecycle and scope of injected objects is critical to ensuring resource efficiency, modularity, and consistent behavior. The **Custom Scope Annotation** named `@ActicityScope` addresses this need by defining a specific scope that limits the lifetime of dependencies to the lifecycle of an activity instance.

This scope ensures that objects annotated with `@ActicityScope` are instantiated once per activity and shared within that activity’s component graph, avoiding unnecessary multiple instances and enabling clean, contextual injection tailored to each activity.

Functionality

The `@ActicityScope` annotation is a lightweight custom qualifier that:

• Defines a Dagger Scope: By marking it with @Scope, it signals to Dagger that this annotation will manage scoping rules.

• Retention Policy: Using @Retention(RetentionPolicy.RUNTIME) ensures that the annotation metadata is available at runtime for Dagger’s reflection and code generation mechanisms.

• Activity Lifecycle Binding: When used on Dagger components or provider methods, it ties the lifecycle of the injected objects to the activity lifecycle, meaning these objects live as long as the activity does.

This behavior supports patterns where certain objects (e.g., `FsmPlayer`, `PlayerControllerUI`) need to be consistent and shared during the entire active period of an activity but should be discarded afterward to avoid memory leaks or stale state.

Code Snippet

@Scope
@Retention(RetentionPolicy.RUNTIME)
public @interface ActicityScope {
}

This concise declaration serves as a marker for Dagger to group and manage scoped instances.

Integration and Relationship

• With Dagger Components and Modules:
  The @ActicityScope annotation is applied to the custom components (FsmComonentReal, FsmComonent) and modules (PlayerModuleDefault, FSMModuleReal) to bind all their provided dependencies to the same activity scope. This ensures that within an activity, there is a single consistent set of injected instances.

• With the Parent Topic (Dependency Injection Setup):
  The parent topic describes how Dagger modules and components provide scoped injection of FSM player, controllers, monitors, and ad interfaces. The @ActicityScope is the custom scope annotation that makes this modularity and lifecycle management possible. It is the foundational mechanism that enables scoped injection beyond the default singleton or unscoped lifetimes.

• With Other Subtopics:
  While other subtopics focus on the concrete modules, components, or injected classes, the custom scope annotation introduces a new concept: scoping rules for dependency lifetimes. It uniquely defines how the injected instances relate to the activity lifecycle, which is not covered by the parent topic or other subtopics that focus more on the "what" rather than the "when/how long".

Example Use in Component Declaration

@ActicityScope
@Component(modules = {PlayerModuleDefault.class})
public interface FsmComonent {
    void inject(DoubleViewTubiPlayerActivity activity);
    // Other injection targets
}

Here, `@ActicityScope` ensures that all dependencies provided by `PlayerModuleDefault` and injected into `DoubleViewTubiPlayerActivity` are scoped to the activity.

Diagram

classDiagram
    class ActicityScope {
        <<interface>>
        +@Scope
        +@Retention(RUNTIME)
    }
    class FsmComonent {
        <<component>>
        +inject(activity)
    }
    class PlayerModuleDefault {
        <<module>>
        +providesDependencies()
    }
    FsmComonent ..|> ActicityScope : scoped with
    PlayerModuleDefault ..|> ActicityScope : scoped provides

This class diagram illustrates how `@ActicityScope` acts as a marker interface linking Dagger components and modules to a specific scoped lifecycle, governing the instances they supply and manage.

By defining `@ActicityScope`, the project ensures that all activity-level dependencies have a controlled lifecycle matching the activity, promoting modularity, memory efficiency, and clear dependency management within the Android media player framework.