FSMModuleReal.java

Overview

`FSMModuleReal` is a Dagger 2 dependency injection module that provides concrete, scoped instances of key playback and ad-related components for the media player system. Designed for real-world use, it supports integration with Android UI elements such as `WebView` and root `View`, enabling advanced ad playback features including VPAID (Video Player Ad-Serving Interface Definition) ads.

This module wires together the finite state machine (FSM) player, playback controllers, ad retrievers, monitors, and a VPAID client, managing their lifecycles under a custom `@ActicityScope`. It simulates asynchronous network retrieval for ads and cue points, facilitating realistic demo or development environments without real ad servers.

Detailed Description

`FSMModuleReal` is responsible for providing instances of classes used throughout the media playback system by leveraging Dagger's `@Provides` methods. The provided dependencies are scoped to an activity lifecycle via the custom `@ActicityScope` annotation.

Key Responsibilities

• Provide the StateFactory that creates FSM playback states.

• Provide the FSM player (FsmPlayerImperial), initializing it to start at the FetchCuePointState.

• Provide UI and ad playback controllers, integrating WebView and root views.

• Provide ad media models with sample ad URLs.

• Simulate asynchronous fetching of ads and cue points with delayed callbacks.

• Provide monitors for ad playing and cue points.

• Provide a real VpaidClient implementation (TubiVPAID) that bridges WebView and FSM player for VPAID ad playback.

Classes and Methods

Class: FSMModuleReal

**Package:** `com.tubitv.media.demo.di`

**Annotations:** `@Module`

**Fields:**

**Constructor:**

public FSMModuleReal(@Nullable WebView webView, @Nullable View rootView)

• Parameters:

  • webView: Nullable WebView instance used for VPAID ad rendering.

  • rootView: Nullable root View of the player UI.

• Description:
  Stores references to UI components for injection into controllers and clients.

Provided Methods (Dagger @Provides annotated)

All methods are scoped with `@ActicityScope`, meaning their instances live as long as the activity lifecycle.

1. provideStateFactory

StateFactory provideStateFactory()

• Returns: StateFactory

• Description:
  Provides a new instance of StateFactory, which is responsible for creating FSM playback states.

• Usage:
  Used by the FSM player to instantiate and manage playback states.

2. provideFsmPlayer

FsmPlayer provideFsmPlayer(StateFactory factory)

• Parameters:

  • factory: StateFactory instance supplied by provideStateFactory().

• Returns:
  FsmPlayer — a concrete FSM player implementation (FsmPlayerImperial).

• Description:
  Provides a new FsmPlayerImperial instance. The overridden method initializeState() sets the initial FSM state as FetchCuePointState.class, initiating playback by fetching cue points.

• Usage Example:

FsmPlayer player = provideFsmPlayer(stateFactory);
Class initialState = player.initializeState(); // returns FetchCuePointState.class

3. provideController

PlayerUIController provideController()

• Returns: PlayerUIController

• Description:
  Provides a PlayerUIController instance constructed with references to the webView and rootView. The first two parameters are passed as null indicating no direct player instances are injected here.

• Usage:
  Manages UI-related playback logic and coordinates the visibility and interaction of video views and WebView.

4. provideComponentController

PlayerAdLogicController provideComponentController()

• Returns: PlayerAdLogicController

• Description:
  Provides a PlayerAdLogicController instance with null parameters, which manages ad-specific playback logic.

5. provideAdRetriever

AdRetriever provideAdRetriever()

• Returns: AdRetriever

• Description:
  Provides an AdRetriever instance representing the ad retrieval data model.

6. provideCuePointsRetriever

CuePointsRetriever provideCuePointsRetriever()

• Returns: CuePointsRetriever

• Description:
  Provides a CuePointsRetriever instance representing the cue points retrieval data model.

7. provideAdPlayingMonitor

AdPlayingMonitor provideAdPlayingMonitor(FsmPlayer player)

• Parameters:

  • player: The FsmPlayer instance to monitor.

• Returns:
  AdPlayingMonitor

• Description:
  Creates an AdPlayingMonitor linked to the FSM player to observe ad playback state.

8. provideCuePointMonitor

CuePointMonitor provideCuePointMonitor(FsmPlayer fsmPlayer)

• Parameters:

  • fsmPlayer: The FSM player to monitor.

• Returns:
  CuePointMonitor

• Description:
  Provides a CuePointMonitor instance with a customized networkingAhead() method returning 5000 ms. This monitors upcoming cue points to trigger ad playback in advance.

• Implementation Detail:
  The cue points array is commented out but could be set manually if needed.

9. provideAdMediaModel

AdMediaModel provideAdMediaModel()

• Returns:
  AdMediaModel — a collection of ad media items.

• Description:
  Constructs an AdMediaModel containing a list of MediaModel ads. It includes two sample advertisement URLs (HTTP HLS streams), one flagged as corrupted (commented out). The nextAD() method returns the first ad in the list or null if none exists.

• Usage:
  Used by the AdInterface to supply ads during playback.

10. provideAdInterfaceNoPreroll

AdInterface provideAdInterfaceNoPreroll()

• Returns:
  AdInterface

• Description:
  Provides an AdInterface implementation that asynchronously fetches ads and cue points with simulated 2000ms network delay using background threads.

• Implementation Detail:

  • fetchAd: Posts a delayed callback on the main thread returning the AdMediaModel created by provideAdMediaModel().

  • fetchQuePoint: Posts a delayed callback returning a fixed array of cue points (milliseconds offset).

• Usage Example:

adInterface.fetchAd(adRetriever, new RetrieveAdCallback() {
    @Override
    public void onReceiveAd(AdMediaModel adMediaModel) {
        // Handle received ad media model
    }
});

11. provideVpaidClient

VpaidClient provideVpaidClient(FsmPlayer player)

• Parameters:

  • player: The FSM player instance.

• Returns:
  VpaidClient

• Description:
  Provides a TubiVPAID client implementation that integrates with the passed WebView, UI thread Handler, and FSM player. This client handles VPAID ad playback inside the WebView, bridging native and JavaScript ad logic.

Important Implementation Details

• Use of Nullable UI Components:
  The module accepts nullable WebView and View references, allowing flexible injection depending on the activity or fragment setup.

• Simulated Asynchronous Networking:
  The AdInterface implementation fakes network latency by sleeping on background threads and posting results on the main thread handler, emulating realistic ad and cue point retrieval.

• Anonymous Subclass of FsmPlayerImperial:
  The FSM player is created via an anonymous subclass overriding initializeState() to start playback state machine at FetchCuePointState.

• Ad Media Model with Hardcoded URLs:
  The ads are hardcoded sample HLS video streams, with one commented corrupted source, illustrating how ads are structured and provided.

• Java 7 Style Anonymous Inner Classes:
  Uses anonymous inner classes and explicit Runnable implementations for compatibility.

Interaction with Other System Components

• Finite State Machine (FSM):
  The FsmPlayerImperial instance provided by this module is the core playback FSM managing playback states and transitions.

• Playback Controllers:
  PlayerUIController and PlayerAdLogicController coordinate UI visibility and ad playback logic, injected with relevant UI references.

• Ad Retrieval & Cue Point Management:
  The AdRetriever and CuePointsRetriever objects together with the asynchronous AdInterface allow the FSM to fetch and schedule ads and cue points.

• VPAID Ad Support:
  The VpaidClient (TubiVPAID) integrates WebView-based VPAID ads, allowing interactive ad playback controlled by the FSM.

• Dependency Injection Lifecycle:
  All provided instances share the @ActicityScope, ensuring consistent lifecycle management within the activity.

Usage Example in Activity

// In an Android activity or fragment:

// Assume webView and rootView are initialized UI components
FSMModuleReal fsmModule = new FSMModuleReal(webView, rootView);

// Using a Dagger component that includes FSMModuleReal
FsmComonentReal component = DaggerFsmComonentReal.builder()
    .fSMModuleReal(fsmModule)
    .build();

component.inject(this);

// Injected fields include:
// - FsmPlayer player;
// - PlayerUIController uiController;
// - PlayerAdLogicController adController;
// - AdInterface adInterface;
// - VpaidClient vpaidClient;
// etc.

// The FSM player can then be started, and ads fetched asynchronously.

Visual Diagram: Class Structure of FSMModuleReal

classDiagram
    class FSMModuleReal {
        -WebView webView
        -View rootView
        +FSMModuleReal(webView, 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
    }

This diagram highlights the main class with its provided methods and injected UI components.

Summary

`FSMModuleReal` is a comprehensive Dagger 2 module that provides real, scoped instances of playback and ad-related components for a media player system with VPAID ad support. It integrates Android UI elements such as `WebView` and root player views, simulates asynchronous ad and cue point fetching, and supplies a concrete FSM player starting from cue point fetching. This module is a key part of the dependency injection setup, enabling modular, testable, and maintainable playback and ad logic integration in the player application.