FetchCuePointState.java

Overview

`FetchCuePointState` is a concrete state class within the Finite State Machine (FSM) playback system, specifically responsible for initiating the retrieval of cue points from the ad server. Cue points are timestamps within the media content that indicate when advertisements (such as preroll, midroll, or postroll ads) should be triggered.

This state plays a critical role in the ad integration workflow by:

• Requesting cue points asynchronously from the ad server using the ad interface.

• Based on the retrieved cue points, determining if a preroll ad exists (cue point at 0).

• Triggering the correct next state transition depending on the presence or absence of preroll ads.

If preroll ads are present, it transitions the FSM to `MakingPrerollAdCallState` for fetching preroll ads. Otherwise, it transitions directly to `MoviePlayingState` to start playing the main content.

Class: FetchCuePointState

Inheritance

• Extends BaseState, which implements the State interface and provides default behavior for state transitions and work execution.

Purpose

Encapsulates the behavior of fetching cue points from the ad server and deciding the next FSM state based on cue point data.

Methods

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

Determines the next state of the FSM based on the input event received.

Parameters

• input (Input, non-null): The event or signal triggering a state transition. Possible inputs relevant to this state include:

  • HAS_PREROLL_AD: Indicates that preroll ads are available (cue point 0 exists).

  • NO_PREROLL_AD: Indicates no preroll ads are present.

• factory (StateFactory, non-null): Factory instance used to create new state instances.

Returns

• State instance representing the next FSM state.

• Returns:

  • MakingPrerollAdCallState instance if preroll ads exist.

  • MoviePlayingState instance if no preroll ads exist.

  • null if the input is unrecognized.

Usage Example

// Example of transitioning to next state based on input
State nextState = fetchCuePointState.transformToState(Input.HAS_PREROLL_AD, stateFactory);
// nextState is MakingPrerollAdCallState instance

void performWorkAndUpdatePlayerUI(@NonNull FsmPlayer fsmPlayer)

Executes the core action of this state, which is to fetch cue points from the ad server asynchronously. It performs no direct UI updates.

Parameters

• fsmPlayer (FsmPlayer, non-null): The FSM player instance that holds necessary interfaces and retrievers.

Behavior

• Calls the superclass implementation for any standard behavior.

• Validates that fsmPlayer is not null.

• Invokes fetchCuePointCall passing:

  • The ad server interface (AdInterface).

  • The cue points retriever (CuePointsRetriever).

  • The callback interface (CuePointCallBack), which is cast to FsmPlayerImperial (the concrete FSM player implementation handling cue point callbacks).

• If any of these dependencies are missing, it logs an error message.

Usage Example

fetchCuePointState.performWorkAndUpdatePlayerUI(fsmPlayer);

private void fetchCuePointCall(AdInterface adInterface, CuePointsRetriever retriever, CuePointCallBack callBack)

Helper method that triggers the asynchronous fetching of cue points from the ad server.

Parameters

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

• retriever (CuePointsRetriever): Object that provides retrieval parameters and state for cue points.

• callBack (CuePointCallBack): Callback to receive cue point results.

Behavior

• Checks all parameters for nullability.

• If valid, calls adInterface.fetchQuePoint(retriever, callBack).

• If any parameter is null, logs an error using ExoPlayerLogger.

Important Implementation Details

• Callback Casting: The performWorkAndUpdatePlayerUI method casts the FsmPlayer instance to FsmPlayerImperial to pass it as a CuePointCallBack. This tightly couples this state to the FsmPlayerImperial implementation, which handles cue point responses and triggers state transitions.

• Null Safety: The class uses nullability annotations (@NonNull, @Nullable) and performs null checks to prevent null pointer exceptions during runtime.

• Transition Logic Simplicity: The state only handles two inputs for transitions: presence or absence of preroll ads, enabling straightforward and predictable state changes.

• Logging: Uses ExoPlayerLogger to report failures in fetching cue points, aiding debugging and monitoring.

Interaction With Other Components

• FsmPlayer / FsmPlayerImperial: This state operates within an FSM player context, using its interfaces and retrievers to fetch cue points. It relies on FsmPlayerImperial to receive callback results.

• AdInterface: Provides the mechanism to communicate with the ad server asynchronously.

• CuePointsRetriever: Supplies parameters and context for cue point retrieval.

• StateFactory: Used to create instances of the next state depending on input.

• Other States:

  • Transitions to MakingPrerollAdCallState if preroll ads are present.

  • Transitions to MoviePlayingState if no preroll ads are available.

Usage Workflow

1. The FSM enters FetchCuePointState when it needs to retrieve cue points.

2. performWorkAndUpdatePlayerUI triggers the asynchronous cue point fetch.

3. Upon receiving cue points, FsmPlayerImperial calls transit with either HAS_PREROLL_AD or NO_PREROLL_AD.

4. transformToState returns the next appropriate state.

5. FSM transitions to the preroll ad fetching state or directly to movie playback.

Mermaid Class Diagram

classDiagram
    class FetchCuePointState {
        +State transformToState(Input input, StateFactory factory)
        +void performWorkAndUpdatePlayerUI(FsmPlayer fsmPlayer)
        -void fetchCuePointCall(AdInterface adInterface, CuePointsRetriever retriever, CuePointCallBack callBack)
    }
    FetchCuePointState --|> BaseState

Summary

`FetchCuePointState` is a critical FSM player state that initiates cue point retrieval to determine ad insertion timing. It acts as a gateway in the ad playback workflow, enabling smooth transitions to preroll ad loading or content playback based on server-provided cue points. Its design emphasizes asynchronous operation, clear transition logic, and integration with the FSM player and ad server interfaces.

Example Usage in FSM Player (Simplified Pseudocode)

// Inside FsmPlayerImperial which implements CuePointCallBack
@Override
public void onCuePointReceived(long[] cuePoints) {
    if (cuePointsContainsPrerollAd(cuePoints)) {
        transit(Input.HAS_PREROLL_AD);
    } else {
        transit(Input.NO_PREROLL_AD);
    }
}

// The FSM Player transitions accordingly
fetchCuePointState.performWorkAndUpdatePlayerUI(fsmPlayer);
// Cue points will be fetched, and callback triggers next transition

References

• BaseState — Base class for all FSM states.

• Input — Enum representing input events triggering state transitions.

• StateFactory — Factory for creating state instances.

• FsmPlayerImperial — Concrete FSM player that handles cue point callbacks.

• AdInterface and CuePointsRetriever — Interfaces used for fetching cue points from the ad server.

• ExoPlayerLogger — Logging utility for error reporting.

End of Documentation for FetchCuePointState.java