MakingPrerollAdCallState.java

Overview

`MakingPrerollAdCallState` is a concrete state class within the Finite State Machine (FSM) playback system of the Tubitv media player. This state encapsulates the logic for initiating the retrieval of preroll advertisements before the main content playback begins.

In the FSM playback lifecycle, this state is responsible for:

• Setting the ad retriever to focus on the preroll cue point (typically cue point 0).

• Making an asynchronous call to the ad server to fetch preroll ads.

• Transitioning to the AdPlayingState once preroll ads are successfully received.

This class extends the generic `BaseState` and overrides key methods to implement preroll-specific ad fetching behavior.

Class: MakingPrerollAdCallState

public class MakingPrerollAdCallState extends BaseState

Inheritance

• Extends: BaseState

• Implements: State interface (inherited via BaseState)

Detailed Description

Purpose

This class represents the FSM state where the system makes a call to retrieve preroll ads. It prepares the necessary context (cue points) for the ad retriever and invokes the ad server interface to fetch ads asynchronously.

Key Responsibilities

• Determine the next state based on input events.

• Prepare and update the ad retriever's cue point to indicate preroll position.

• Initiate the ad retrieval call.

• Log errors if prerequisites for fetching ads are missing.

Methods

1. transformToState

@Nullable
@Override
public State transformToState(@NonNull Input input, @NonNull StateFactory factory)

Description

Determines the next state based on the given input event. This method implements the FSM transition logic specific to preroll ad fetching.

Parameters

• input (Input): The input event or signal that may trigger a state transition.

• factory (StateFactory): Factory instance used to create new state objects.

Returns

• State: The next state to transition into, or null if no transition occurs.

Behavior

• If the input is PRE_ROLL_AD_RECEIVED, it transitions to the AdPlayingState to begin preroll ad playback.

• For all other inputs, no state transition occurs (returns null).

Usage Example

State nextState = makingPrerollAdCallState.transformToState(Input.PRE_ROLL_AD_RECEIVED, stateFactory);
if (nextState != null) {
    fsmPlayer.setCurrentState(nextState);
}

2. performWorkAndUpdatePlayerUI

@Override
public void performWorkAndUpdatePlayerUI(@NonNull FsmPlayer fsmPlayer)

Description

Executes the preroll ad retrieval process and updates the player UI as necessary. This method is called when the FSM enters this state.

Parameters

• fsmPlayer (FsmPlayer): The FSM player instance executing the state logic; provides access to player controllers, ad servers, and retrievers.

Behavior

• Calls the superclass implementation (for any base work).

• Checks if the player instance is null; if so, terminates early.

• Updates the AdRetriever's cue point to 0 (preroll) or to a historical position if playback history exists.

• Calls the helper method fetchAd to request preroll ads asynchronously.

Usage Example

makingPrerollAdCallState.performWorkAndUpdatePlayerUI(fsmPlayer);

3. fetchAd

private void fetchAd(AdInterface adInterface, AdRetriever retriever, RetrieveAdCallback callback)

Description

Helper method to request ads from the ad server interface.

Parameters

• adInterface (AdInterface): Interface used to communicate with the ad server.

• retriever (AdRetriever): Object encapsulating ad request parameters, including cue points.

• callback (RetrieveAdCallback): Callback interface to handle ad retrieval responses.

Behavior

• Validates that none of the parameters are null.

• If valid, invokes fetchAd on the adInterface.

• If any parameter is null, logs an error message indicating failure to fetch ads.

Logging

• Uses ExoPlayerLogger to log errors tagged with FSMPLAYER_TESTING.

Implementation Details and Algorithms

• Cue Point Management:
  Before making the ad call, the state updates the AdRetriever with the correct cue point indicating where in the playback timeline the ad should be inserted. For preroll ads, this is typically cue point 0. If playback history exists (e.g., resuming playback), it uses the last known history position.

• Asynchronous Ad Fetching:
  The actual call to fetch ads is asynchronous. The state invokes fetchAd on the AdInterface, passing the AdRetriever and a callback (RetrieveAdCallback) which will handle responses (e.g., success or failure). The FSM listens for the PRE_ROLL_AD_RECEIVED input to proceed.

• State Transitions:
  Transition out of this state only occurs on the input PRE_ROLL_AD_RECEIVED, ensuring that ad playback does not start until ads are successfully loaded.

• Error Handling:
  If essential components (adInterface, retriever, or callback) are missing, the state logs an error but does not crash, allowing the FSM or higher-level components to handle fallback logic.

Interactions with Other System Components

• FSM Player (FsmPlayer):
  This state interacts closely with the FSM player instance to retrieve the ad server interface, the ad retriever, and to update cue points based on playback history.

• Ad Server Interface (AdInterface):
  The state calls fetchAd on this interface to asynchronously request preroll ads.

• Ad Retriever (AdRetriever):
  Holds the parameters for the ad request, including cue point information, which is updated by this state.

• Retrieve Ad Callback (RetrieveAdCallback):
  Provided by the FSM player, this callback handles responses from the ad server and triggers FSM input signals that cause transitions.

• State Factory (StateFactory):
  Used to create the next FSM state object (AdPlayingState) upon receiving preroll ads.

• Logging Utility (ExoPlayerLogger):
  Used for diagnostic logs, particularly in error scenarios.

Usage Scenario Example

// Assuming fsmPlayer is the current FSM player instance and stateFactory is available

// Instantiate the preroll ad call state (normally done via factory)
MakingPrerollAdCallState prerollAdState = new MakingPrerollAdCallState();

// FSM enters preroll ad fetching state
fsmPlayer.setCurrentState(prerollAdState);

// FSM triggers the work to fetch preroll ads
prerollAdState.performWorkAndUpdatePlayerUI(fsmPlayer);

// Later, when ads are received:
State nextState = prerollAdState.transformToState(Input.PRE_ROLL_AD_RECEIVED, stateFactory);
if (nextState != null) {
    fsmPlayer.setCurrentState(nextState);
    // The player will now start playing the preroll ads
}

Visual Diagram: Class Structure of MakingPrerollAdCallState

classDiagram
    class MakingPrerollAdCallState {
        +State transformToState(Input input, StateFactory factory)
        +void performWorkAndUpdatePlayerUI(FsmPlayer fsmPlayer)
        -void fetchAd(AdInterface adInterface, AdRetriever retriever, RetrieveAdCallback callback)
    }
    MakingPrerollAdCallState --|> BaseState
    BaseState --|> State

• MakingPrerollAdCallState inherits from BaseState, which implements the State interface.

• Public methods override base behavior to provide preroll-specific ad fetching and state transition logic.

• Private helper method fetchAd encapsulates the ad request logic.

Summary

`MakingPrerollAdCallState` is a pivotal FSM playback state responsible for initiating preroll ad retrieval. It updates the ad retriever's cue point contextually based on playback history, invokes the ad server interface to fetch ads asynchronously, and transitions to ad playback upon successful ad reception. This state ensures preroll ads are fetched and played seamlessly before the main content, contributing to a smooth and integrated user viewing experience.

If you need further details on related classes like `AdPlayingState`, `FsmPlayer`, or `StateFactory`, please refer to their respective documentation pages.