Dagger Modules

Purpose

Dagger Modules provide scoped and configurable instances of core playback components such as the FSM player, UI and ad controllers, ad and cue point retrievers, monitors, and VPAID client implementations. This subtopic addresses the need for flexible dependency provisioning that supports different runtime environments (e.g., real app with WebView-based VPAID or default/mock setups) while ensuring modularity, testability, and lifecycle management.

By encapsulating the creation logic of these dependencies, Dagger Modules support injection with a consistent lifecycle scope (`@ActicityScope`). This isolates configuration details from consumers and enables smooth swapping or extension of components without affecting the rest of the system.

Functionality

Key Responsibilities of Dagger Modules

• Provide FSM Player and State Factory
  The FSM player (FsmPlayerImperial) controls playback state transitions and initiates from a defined initial state (FetchCuePointState). The StateFactory supplies concrete state implementations to the FSM.

• Instantiate Playback Controllers
  PlayerUIController manages UI-related playback logic, including interaction with WebView and root views when applicable.
  PlayerAdLogicController handles ad-specific playback behavior.

• Supply Ad and Cue Point Retrievers
  These retrievers asynchronously fetch ad media data and cue points, essential for triggering midroll/preroll/postroll ads.

• Provide Playback Monitors
  Monitors like AdPlayingMonitor and CuePointMonitor observe playback progress and notify the FSM of relevant events, such as reaching cue points or ad completion.

• Implement Ad Interfaces and VPAID Clients
  The AdInterface defines how ads and cue points are fetched; modules can provide real networking implementations or mock/stub versions with simulated delays.
  The VpaidClient manages VPAID ad playback lifecycle and communication, either as a no-op stub or a real WebView-based client.

Differences Between Modules

Two provided modules illustrate typical variations:

• PlayerModuleDefault
  Supplies simple, default implementations with no WebView or root view dependencies.
  Uses immediate callbacks in AdInterface, no delays or real networking.
  Provides a stub VpaidClient that performs no operations.

• FSMModuleReal
  Designed for real playback scenarios with WebView-based VPAID ads and UI integration.
  Accepts nullable WebView and root view references to pass into controllers and VPAID client.
  Implements asynchronous AdInterface with simulated network delays using background threads and handlers.
  Provides a real TubiVPAID client tied to the WebView and FSM player.

Example Snippet: Providing FSM Player

@ActicityScope
@Provides
FsmPlayer provideFsmPlayer(StateFactory factory) {
    return new FsmPlayerImperial(factory) {
        @Override
        public Class initializeState() {
            return FetchCuePointState.class;
        }
    };
}

This snippet shows how the FSM player is initialized with a factory and the starting state, ensuring consistent FSM setup across injection contexts.

Example Snippet: Ad Interface with Simulated Delay (FSMModuleReal)

@ActicityScope
@Provides
AdInterface provideAdInterfaceNoPreroll() {
    return new AdInterface() {
        @Override
        public void fetchAd(AdRetriever retriever, final RetrieveAdCallback callback) {
            new Thread(() -> {
                try { Thread.sleep(2000); } catch (InterruptedException ignored) {}
                new Handler(Looper.getMainLooper()).post(() -> callback.onReceiveAd(provideAdMediaModel()));
            }).start();
        }

        @Override
        public void fetchQuePoint(CuePointsRetriever retriever, final CuePointCallBack callBack) {
            new Thread(() -> {
                try { Thread.sleep(2000); } catch (InterruptedException ignored) {}
                new Handler(Looper.getMainLooper()).post(() -> callBack.onCuePointReceived(new long[] { 0, 60000, 900000, 1800000, 3600000 }));
            }).start();
        }
    };
}

This implementation simulates network latency for fetching ads and cue points, illustrating how the module abstracts data provision behind asynchronous callbacks.

Relationship to Parent Topic and Other Subtopics

Dagger Modules are foundational to the **Dependency Injection Setup** parent topic, concretely supplying the runtime instances of FSM player, controllers, retrievers, monitors, and VPAID clients. They define *how* these dependencies are constructed and scoped, complementing the components and custom scope annotations that manage *where* and *when* the dependencies live.

By isolating the provisioning logic:

• Higher-level components like activities and FSM states receive ready-to-use objects without coupling to initialization details.

• Other subtopics (e.g., FSM playback, Ad and Cue Point Management, VPAID Ad Integration, Media Playback and UI Controls) rely on these modules to inject correct implementations tailored to their execution context.

• Switching between mock, default, or real implementations (such as enabling VPAID support via WebView) becomes straightforward without rewriting dependent logic.

This modular injection approach underpins the entire media playback system's flexibility and maintainability.

Diagram

classDiagram
    class FSMModuleReal {
        +WebView webView
        +View rootView
        +provideStateFactory() StateFactory
        +provideFsmPlayer(StateFactory) FsmPlayer
        +provideController() PlayerUIController
        +provideComponentController() PlayerAdLogicController
        +provideAdRetriever() AdRetriever
        +provideCuePointsRetriever() CuePointsRetriever
        +provideAdPlayingMonitor(FsmPlayer) AdPlayingMonitor
        +provideCuePointMonitor(FsmPlayer) CuePointMonitor
        +provideAdMediaModel() AdMediaModel
        +provideAdInterfaceNoPreroll() AdInterface
        +provideVpaidClient(FsmPlayer) VpaidClient
    }

    class PlayerModuleDefault {
        +provideStateFactory() StateFactory
        +provideFsmPlayer(StateFactory) FsmPlayer
        +provideController() PlayerUIController
        +provideComponentController() PlayerAdLogicController
        +provideAdRetriever() AdRetriever
        +provideCuePointsRetriever() CuePointsRetriever
        +provideAdPlayingMonitor(FsmPlayer) AdPlayingMonitor
        +provideCuePointMonitor(FsmPlayer) CuePointMonitor
        +provideAdMediaModel() AdMediaModel
        +provideAdInterfaceNoPreroll() AdInterface
        +provideVpaidClient() VpaidClient
    }

    FSMModuleReal ..|> PlayerModuleDefault : extends/overrides

    FSMModuleReal --> WebView
    FSMModuleReal --> View
    FSMModuleReal --> FsmPlayer
    FSMModuleReal --> PlayerUIController
    FSMModuleReal --> PlayerAdLogicController
    FSMModuleReal --> AdRetriever
    FSMModuleReal --> CuePointsRetriever
    FSMModuleReal --> AdPlayingMonitor
    FSMModuleReal --> CuePointMonitor
    FSMModuleReal --> AdInterface
    FSMModuleReal --> VpaidClient

    PlayerModuleDefault --> FsmPlayer
    PlayerModuleDefault --> PlayerUIController
    PlayerModuleDefault --> PlayerAdLogicController
    PlayerModuleDefault --> AdRetriever
    PlayerModuleDefault --> CuePointsRetriever
    PlayerModuleDefault --> AdPlayingMonitor
    PlayerModuleDefault --> CuePointMonitor
    PlayerModuleDefault --> AdInterface
    PlayerModuleDefault --> VpaidClient

This class diagram highlights the two main Dagger modules that provide scoped instances of critical playback components, showing their key methods and relationships. `FSMModuleReal` extends or overrides the default provisioning to support real-world playback scenarios involving WebView and asynchronous ad fetching.

By centralizing and scoping the provisioning of playback components, Dagger Modules enable a clean, modular architecture that supports flexible runtime configurations and simplifies testing and maintenance.