Input.java

Overview

`Input.java` defines an enumeration `Input` representing the various input events or triggers that drive the state transitions within a finite state machine (FSM) managing media playback and ad interactions in the Tubi TV media player system.

Each enum constant corresponds to a specific input event expected by one or more concrete FSM states. These inputs represent key moments in ad fetching, ad playing, movie playback, error handling, and user interactions with ads. By modeling inputs as an enum, the FSM implementation gains type safety, clarity, and easier maintenance.

This file is a core part of the FSM subsystem (`com.tubitv.media.fsm` package), enabling different FSM states (found in subpackages such as `concrete` and specific classes like `VastAdInteractionSandBoxState`) to react consistently to external and internal triggers.

Enum: Input

`Input` is an enum that enumerates all possible input events recognizable by the media FSM. Each input corresponds to a particular state or group of states within the FSM, as indicated by associated comments referencing those states.

Enum Constants and Their Intended Contexts

Usage Example

// Example usage in FSM state transition logic:
switch (input) {
    case HAS_PREROLL_AD:
        // Transition to preroll ad setup state
        fsm.transitionTo(PrerollAdSetupState.class);
        break;
    case AD_FINISH:
        // Proceed to next ad or resume content playback
        fsm.transitionTo(NextAdOrContentState.class);
        break;
    case ERROR:
        // Handle error scenario
        fsm.transitionTo(ErrorState.class);
        break;
    default:
        // Handle other inputs or ignore
        break;
}

Implementation Details

• The enum does not contain fields, methods, or constructors beyond the enum constants.

• Each input is documented with the FSM state class that expects it, serving as inline guidance for developers navigating the FSM's event-driven flow.

• This approach helps tightly couple inputs with states, improving maintainability and reducing the likelihood of input misuse.

• The enum is part of a larger FSM design pattern implementation where inputs trigger state transitions.

Interactions with Other Components

• FSM States (com.tubitv.media.fsm.concrete package): The inputs are consumed by concrete state classes such as FetchCuePointState, MakingPrerollAdCallState, MakingAdCallState, ReceiveAdState, AdPlayingState, VpaidState, MoviePlayingState, and the sandbox state VastAdInteractionSandBoxState.

• FSM Controller/Manager: The FSM controller listens for external events (e.g., ad availability, user interactions, playback events) and converts them into Input enum events to drive the FSM.

• Ad Systems Integration: Inputs like AD_RECEIVED, PRE_ROLL_AD_RECEIVED, and VPAID_MANIFEST indicate integration points with ad servers and standards such as VAST and VPAID.

• Media Playback Engine: Inputs such as MAKE_AD_CALL and MOVIE_FINISH are linked to controlling the video playback lifecycle.

• Error Handling Subsystem: The ERROR input allows the FSM to transition into error states and trigger recovery or user notifications.

Visual Diagram

The following Mermaid class diagram illustrates the `Input` enum with its constants, highlighting its role as an event source for FSM states.

classDiagram
    class Input {
        <<enumeration>>
        +HAS_PREROLL_AD
        +NO_PREROLL_AD
        +PRE_ROLL_AD_RECEIVED
        +AD_RECEIVED
        +EMPTY_AD
        +SHOW_ADS
        +NEXT_AD
        +AD_CLICK
        +AD_FINISH
        +VPAID_MANIFEST
        +VPAID_FINISH
        +BACK_TO_PLAYER_FROM_VAST_AD
        +MAKE_AD_CALL
        +MOVIE_FINISH
        +ERROR
        +INITIALIZE
    }

    %% FSM States that consume Input events
    class FetchCuePointState
    class MakingPrerollAdCallState
    class MakingAdCallState
    class ReceiveAdState
    class AdPlayingState
    class VpaidState
    class VastAdInteractionSandBoxState
    class MoviePlayingState
    class ErrorState

    Input <|-- FetchCuePointState : expects HAS_PREROLL_AD, NO_PREROLL_AD
    Input <|-- MakingPrerollAdCallState : expects PRE_ROLL_AD_RECEIVED
    Input <|-- MakingAdCallState : expects AD_RECEIVED, EMPTY_AD
    Input <|-- ReceiveAdState : expects SHOW_ADS
    Input <|-- AdPlayingState : expects NEXT_AD, AD_CLICK, AD_FINISH, VPAID_MANIFEST
    Input <|-- VpaidState : expects VPAID_FINISH
    Input <|-- VastAdInteractionSandBoxState : expects BACK_TO_PLAYER_FROM_VAST_AD
    Input <|-- MoviePlayingState : expects MAKE_AD_CALL, MOVIE_FINISH
    Input <|-- ErrorState : expects ERROR

Summary

• Input.java defines all possible input events that drive state transitions in the media playback and ad FSM.

• The enum is tightly coupled with specific FSM states, improving clarity and reducing errors.

• It supports ad fetching, ad playing, movie playback, user interaction, VAST/VPAID ad handling, and error management.

• This file is a foundational building block within the FSM subsystem in the Tubi TV media player architecture, enabling clear, maintainable event-driven workflows.

This documentation should allow developers and architects to understand the role, usage, and context of `Input.java` within the wider media FSM system.