MakingAdCallState.java

Overview

`MakingAdCallState` is a concrete implementation of a playback state within the Finite State Machine (FSM) architecture of the media player system. Its primary responsibility is to handle the process of fetching advertisements from the ad server during playback, typically for midroll or other non-preroll ads.

In this state, the player initiates an ad retrieval call asynchronously through the `AdInterface` and manages transitions based on input events such as the reception of ads or empty ad responses. Once an ad is received, the FSM transitions to the appropriate subsequent state to play the ad or handle the absence of ads.

This class extends `BaseState` and overrides key methods to implement its specific behavior in the playback lifecycle.

Class: MakingAdCallState

Package

com.tubitv.media.fsm.concrete

Inheritance

• Extends: BaseState

• Implements: State (via BaseState)

Purpose

Represents the "Making Ad Call" state in the FSM, responsible for:

• Triggering an ad fetch request to the ad server.

• Handling state transitions triggered by ad-related inputs.

• Performing work required to update the player (fetch ads) without direct UI updates in this state.

Detailed Explanation

Methods

transformToState(Input input, StateFactory factory)

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

**Description:** Determines the next state based on the input event received while in the `MakingAdCallState`.

**Parameters:**

• Input input — An enum representing the input event that may trigger a state transition.

• StateFactory factory — Factory instance used to create other state instances.

**Returns:**

• A State instance representing the next state after transition, or null if no valid transition exists.

**Behavior:**

• On input AD_RECEIVED: transitions to ReceiveAdState to process the received ad.

• On input EMPTY_AD: returns null indicating no transition (could be handled by the FSM to fallback).

• On input MAKE_AD_CALL: returns a new MakingAdCallState instance (possibly to retry or refresh ad call).

• On input PRE_ROLL_AD_RECEIVED: transitions to AdPlayingState to start ad playback.

**Usage Example:**

State nextState = makingAdCallState.transformToState(Input.AD_RECEIVED, stateFactory);

performWorkAndUpdatePlayerUI(@NonNull FsmPlayer fsmPlayer)

@Override
public void performWorkAndUpdatePlayerUI(@NonNull FsmPlayer fsmPlayer)

**Description:** Executes the main work of the state, which involves fetching the ad from the ad server via the `AdInterface`.

**Parameters:**

• @NonNull FsmPlayer fsmPlayer — The FSM player instance that holds player state, controllers, and interfaces for ads.

**Returns:** `void`

**Behavior:**

• Calls the superclass method to perform any base logic.

• Checks for null player reference; if null, returns early.

• Calls the private fetchAd method passing in the player's ad interface, ad retriever, and itself as the callback.

• Does not perform any UI updates in this state.

**Usage Example:**

makingAdCallState.performWorkAndUpdatePlayerUI(fsmPlayer);

fetchAd(AdInterface adInterface, AdRetriever retriever, RetrieveAdCallback callback)

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

**Description:** Helper method to initiate the ad retrieval process.

**Parameters:**

• AdInterface adInterface — Interface to communicate with the ad server.

• AdRetriever retriever — Model holding details about the ad request.

• RetrieveAdCallback callback — Callback to handle the response of the ad fetch.

**Returns:** `void`

**Behavior:**

• If all parameters are non-null, calls adInterface.fetchAd(retriever, callback) to start the ad fetch asynchronously.

• Otherwise, logs an error indicating a failure due to missing parameters.

**Usage:**

This method is invoked internally by `performWorkAndUpdatePlayerUI`.

Important Implementation Details

• State Transitions:
  The transitions are based strictly on the input events defined in the FSM (Input enum), ensuring predictable playback flow. For example, receiving an ad triggers a transition to ReceiveAdState, while receiving a preroll ad triggers a transition to AdPlayingState.

• Ad Fetching:
  The actual ad retrieval is performed asynchronously using an AdInterface implementation, with the current state acting as a callback handler. This design decouples the fetching mechanism from playback logic and adheres to asynchronous programming best practices.

• No UI Updates:
  This state does not update the UI directly. Its primary role is to issue the ad fetch request and rely on subsequent states to handle playback and UI changes.

• Error Handling:
  If the AdInterface or AdRetriever is null, an error is logged. The state does not throw exceptions but relies on FSM mechanisms or external logic to handle failure scenarios.

Interaction with Other Components

FSM Player (FsmPlayer)

• MakingAdCallState receives a reference to the active FsmPlayer to access the ad server interface (getAdServerInterface()), the ad retriever (getAdRetriever()), and itself as the callback.

• The state performs its work by requesting ads through the player’s interfaces.

State Factory (StateFactory)

• Used to instantiate next states during transitions, ensuring singleton state management and reducing overhead.

Other States

• ReceiveAdState: Next state after an ad is received, responsible for preparing the player to play the ad.

• AdPlayingState: State responsible for actual ad playback.

• MakingAdCallState (self transition): Allows retrying ad calls without leaving the state.

Ad Interfaces

• AdInterface: Provides the method fetchAd(AdRetriever, RetrieveAdCallback) to fetch ads from the ad server.

• AdRetriever: Contains ad request parameters that are sent to the ad server.

• RetrieveAdCallback: Interface implemented by this state (or passed as callback) to receive ad fetch results.

Usage Example

FsmPlayer player = ...; // FsmPlayer instance properly initialized
StateFactory factory = new StateFactory();

MakingAdCallState makingAdCallState = factory.createState(MakingAdCallState.class);

// Perform work: fetch the ad asynchronously
makingAdCallState.performWorkAndUpdatePlayerUI(player);

// Later, upon receiving input event AD_RECEIVED from the ad fetch callback:
State nextState = makingAdCallState.transformToState(Input.AD_RECEIVED, factory);

// Transition to ReceiveAdState for ad preparation
player.setCurrentState(nextState);
nextState.performWorkAndUpdatePlayerUI(player);

Visual Diagram

classDiagram
    class MakingAdCallState {
        +transformToState(input: Input, factory: StateFactory): State
        +performWorkAndUpdatePlayerUI(fsmPlayer: FsmPlayer): void
        -fetchAd(adInterface: AdInterface, retriever: AdRetriever, callback: RetrieveAdCallback): void
    }
    MakingAdCallState --|> BaseState
    MakingAdCallState ..> AdInterface : uses
    MakingAdCallState ..> AdRetriever : uses
    MakingAdCallState ..> RetrieveAdCallback : implements
    MakingAdCallState ..> FsmPlayer : interacts with

    %% Transitions
    MakingAdCallState "1" --> "1" ReceiveAdState : on AD_RECEIVED
    MakingAdCallState "1" --> "1" AdPlayingState : on PRE_ROLL_AD_RECEIVED
    MakingAdCallState "1" --> "1" MakingAdCallState : on MAKE_AD_CALL

Summary

`MakingAdCallState` is a pivotal FSM state responsible for initiating asynchronous ad fetch calls to the ad server during playback. It waits for input events indicating the success or failure of ad retrieval and transitions accordingly. It does not update the UI directly but triggers the FSM to continue with appropriate ad playback or fallback states. Its design leverages dependency injection of interfaces and a factory pattern for state instantiation, promoting modularity and testability within the FSM playback framework.

References

• Input enum: Defines event inputs triggering state transitions (e.g., AD_RECEIVED, EMPTY_AD, MAKE_AD_CALL).

• StateFactory: Factory pattern implementation for creating and caching state instances.

• FsmPlayer: Core player controller managing state, playback, and ad retrieval interfaces.

• AdInterface: Interface to interact with the ad server.

• AdRetriever: Model that holds ad request information.

• RetrieveAdCallback: Callback interface for ad retrieval responses.

• BaseState: Abstract base class providing default state behaviors.

See Also

• ReceiveAdState.java — Handles ad reception and prepares playback.

• AdPlayingState.java — Manages ad playback lifecycle and UI updates.

• MakingPrerollAdCallState.java — Similar to MakingAdCallState but focused on preroll ads.

• StateFactory.java — Manages instantiation and caching of FSM states.

End of Documentation for MakingAdCallState.java