AdMediaModel.java

Overview

The [AdMediaModel.java](/projects/288/68370) file defines the `AdMediaModel` class, which serves as a container for managing a collection of advertisement media items (`MediaModel` instances). It encapsulates a list of ads typically representing an **Ad Break**—a sequence of advertisements to be played together during media playback.

This class provides utility methods to:

• Access the next ad to be played without removing it.

• Remove the first ad after it has been played.

• Retrieve the count of remaining ads.

By abstracting the ad break concept, `AdMediaModel` simplifies the ad playback logic within the media player system, enabling orderly consumption of ads during preroll, midroll, or postroll ad breaks.

Class: AdMediaModel

public class AdMediaModel {
    private List<MediaModel> listOfAds;

    public AdMediaModel(@NonNull List<MediaModel> listOfAds) { ... }

    @Nullable
    public MediaModel nextAD() { ... }

    public List<MediaModel> getListOfAds() { ... }

    public void popFirstAd() { ... }

    public int nubmerOfAd() { ... }
}

Description

`AdMediaModel` wraps a list of `MediaModel` objects, each representing a single ad. It is primarily used to represent an **Ad Break**, which contains multiple ads to be played sequentially.

Fields

Constructors

AdMediaModel(List<MediaModel> listOfAds)

• Purpose: Initializes a new AdMediaModel instance with a given list of ads.

• Parameters:

  • listOfAds (@NonNull List<MediaModel>): The list of ads to store in this ad break. Must not be null.

**Example:**

List<MediaModel> ads = new ArrayList<>();
ads.add(MediaModel.ad("http://example.com/ad1.m3u8", "http://advertiser.com", false));
ads.add(MediaModel.ad("http://example.com/ad2.m3u8", null, false));

AdMediaModel adBreak = new AdMediaModel(ads);

Methods

@Nullable MediaModel nextAD()

• Purpose: Returns the first ad in the list without removing it. This represents the next ad to be played.

• Returns: The first MediaModel instance if the list is non-empty; otherwise, null.

**Usage Example:**

MediaModel nextAd = adBreak.nextAD();
if (nextAd != null) {
    // Prepare to play nextAd
}

List<MediaModel> getListOfAds()

• Purpose: Returns the underlying list of ads.

• Returns: The list of MediaModel ads (may be empty or null if uninitialized).

void popFirstAd()

• Purpose: Removes the first ad from the list, typically after it has been played.

• Behavior: Only removes if the list is non-null and not empty; otherwise, does nothing.

**Usage Example:**

// After playing the current ad
adBreak.popFirstAd();

int nubmerOfAd()

• Purpose: Returns the number of ads remaining in the list.

• Returns: Count of ads, or zero if the list is null.

**Note:** There is a minor typo in the method name; it should ideally be `numberOfAd()` for clarity.

**Usage Example:**

int remainingAds = adBreak.nubmerOfAd();

Important Implementation Details

• Null Safety: The class handles potential null lists gracefully, returning null for nextAD() and zero for nubmerOfAd() if the list is not initialized.

• List Mutation: The popFirstAd() method modifies the internal ads list by removing the first element, enabling sequential consumption of ads.

• Annotations: Uses Android @NonNull and @Nullable annotations for compile-time null checks, improving code safety.

Interaction with Other System Components

• MediaModel: The AdMediaModel depends on MediaModel instances as the fundamental unit of ads. MediaModel encapsulates metadata and playback URLs for individual ads.

• FSM Player & Ad Controllers: During ad playback, the finite state machine (FSM) managing playback uses AdMediaModel to iterate through ads in an Ad Break. It calls nextAD() to get the current ad and popFirstAd() after playback.

• Ad Retrieval Components: When ad data is fetched from ad servers or parsed from manifests, collections of MediaModel ads are wrapped into AdMediaModel instances for playback management.

• UI Components: UI controllers can query nubmerOfAd() to display the number of upcoming ads or to update progress indicators within an ad break.

Usage Scenario Example

// Assume adList is fetched or constructed elsewhere
AdMediaModel adBreak = new AdMediaModel(adList);

while (adBreak.nubmerOfAd() > 0) {
    MediaModel currentAd = adBreak.nextAD();
    if (currentAd != null) {
        playAd(currentAd);  // Method to play the ad
        adBreak.popFirstAd();
    }
}

Class Diagram

classDiagram
    class AdMediaModel {
        - List~MediaModel~ listOfAds
        + AdMediaModel(listOfAds)
        + nextAD() MediaModel
        + getListOfAds() List~MediaModel~
        + popFirstAd() void
        + nubmerOfAd() int
    }

    class MediaModel {
        <<external>>
    }

    AdMediaModel "1" --> "*" MediaModel : contains >

Summary

`AdMediaModel` is a simple yet crucial class that models an ad break as a list of ads (`MediaModel` objects). It provides methods to access and consume ads sequentially, enabling the media player to manage ad playback cleanly and efficiently. Its integration with other playback components ensures smooth transitions between content and ads, supporting features like midrolls and prerolls in the overall media playback workflow.

End of AdMediaModel.java Documentation