AdRetriever.java

Overview

The `AdRetriever` class serves as a simple data model that encapsulates the key attributes required to request video advertisements from an ad server. It holds identifying information about the media content and context—specifically, the video ID, publisher ID, and the cue point timestamp (referred to as `cubPoint`) indicating when the ad should be played during video playback.

This class is a fundamental part of the ad fetching mechanism within the larger media playback system. It provides a structured way to package ad request parameters that other components, such as the finite state machine (FSM) controlling ad and content playback, use to communicate with the ad server.

Class Details

`AdRetriever`

public class AdRetriever {
    private String videoId;
    private String publisherId;
    private long cubPoint;

    public AdRetriever() { }

    public AdRetriever(String videoId, String publisherId, long cubPoint) { ... }

    public String getVideoId() { ... }
    public void setVideoId(String videoId) { ... }

    public String getPublisherId() { ... }
    public void setPublisherId(String publisherId) { ... }

    public long getCubPoint() { ... }
    public void setCubPoint(long cubPoint) { ... }
}

Properties

Property	Type	Description
`videoId`	String	Unique identifier for the video content for which ads are being requested.
`publisherId`	String	Identifier for the publisher or channel associated with the video, used for ad targeting.
`cubPoint`	long	The cue point timestamp in milliseconds, indicating the exact point in the video timeline where the ad should be inserted.

Constructors

AdRetriever()
Default no-argument constructor that creates an empty AdRetriever instance. Properties can be set later via setters.
AdRetriever(String videoId, String publisherId, long cubPoint)
Parameterized constructor to initialize all properties at the time of object creation.
Parameters:
- videoId: Video identifier.
- publisherId: Publisher identifier.
- cubPoint: Cue point in milliseconds.
**Example:**
```
AdRetriever adRequest = new AdRetriever("vid123", "pub456", 30000L);
```

Getters and Setters

String getVideoId() / void setVideoId(String videoId)
Accessor and mutator for the videoId property.
String getPublisherId() / void setPublisherId(String publisherId)
Accessor and mutator for the publisherId property.
long getCubPoint() / void setCubPoint(long cubPoint)
Accessor and mutator for the cubPoint property.

Usage Example

Below is a typical usage scenario where an `AdRetriever` instance is created and populated for requesting ads aligned with a specific video and cue point:

// Assume these values are dynamically determined during playback
String currentVideoId = "video_abc123";
String currentPublisherId = "publisher_xyz789";
long currentCuePoint = 45000L; // 45 seconds into the video

AdRetriever adRequest = new AdRetriever(currentVideoId, currentPublisherId, currentCuePoint);

// This adRequest object can now be sent to the ad server interface
adInterface.fetchAds(adRequest);

Implementation Details

The class is a Plain Old Java Object (POJO) with private fields and standard getters/setters.
No validation or business logic is embedded in this class; it strictly acts as a data container.
The cubPoint is stored as a long representing milliseconds, allowing precise timing for midroll ad insertion.
The class is designed for easy serialization or conversion to network request parameters when interfacing with ad servers.

Interaction with Other System Components

Finite State Machine (FSM):
The FSM controlling playback uses AdRetriever instances to package and store ad request parameters when transitioning to states responsible for fetching ads (e.g., preroll or midroll ad call states).
Cue Point Detection:
When a cue point is detected during content playback, the FSM updates or creates an AdRetriever object with the current cue point position to initiate the correct ad retrieval.
Ad Fetching Service / Network Layer:
The AdRetriever object is passed to the networking component responsible for communicating with the ad server. This decouples the ad request data from networking implementation details.
Ad Playback Components:
Once ads are fetched using the parameters encapsulated by AdRetriever, the ad playback system uses these to schedule and play ads at the correct playback moments.

Visual Diagram: Class Structure of `AdRetriever`

classDiagram
    class AdRetriever {
        -videoId: String
        -publisherId: String
        -cubPoint: long
        +AdRetriever()
        +AdRetriever(videoId: String, publisherId: String, cubPoint: long)
        +getVideoId(): String
        +setVideoId(videoId: String): void
        +getPublisherId(): String
        +setPublisherId(publisherId: String): void
        +getCubPoint(): long
        +setCubPoint(cubPoint: long): void
    }

Summary

The `AdRetriever` class is a lightweight, focused data model integral to the ad fetching process in the media playback system. It encapsulates the minimal but critical information required to request ads targeted to a specific video and cue point, enabling the system to synchronize ad playback with content seamlessly. Its design promotes clean separation of concerns by abstracting ad request data from playback logic and network communication.

Additional Context (From Related Documentation)

The cubPoint corresponds to cue points identified by the CuePointsRetriever class, which marks where ads should be inserted.
The FSM uses AdRetriever to trigger transitions such as making an ad call and playing ads at the correct time during video playback.
Playback monitoring components check progress and cue points, updating or using AdRetriever instances accordingly.

This class is therefore a cornerstone of the ad and cue point management ecosystem within the application.

End of Documentation for AdRetriever.java