State Factory

Purpose

The State Factory addresses the need for efficient and flexible management of finite state machine (FSM) state instances within media playback. Specifically, it solves two problems:

1. Instance Reuse: Avoids creating multiple instances of the same FSM state by caching singleton instances. This reduces memory overhead and ensures consistent state behavior.

2. Customization Support: Enables substitution of default FSM state implementations with custom subclasses. This allows developers to override or extend core state behaviors without modifying the FSM core or other subtopics.

By centralizing state creation and caching, the State Factory simplifies FSM state management and promotes modular extensibility for playback state transitions.

Functionality

The State Factory acts as a centralized creator and cache for all FSM state instances used by the playback FSM. Its key workflows and capabilities include:

• Singleton State Caching: Maintains a map from each state class type to a single instance. When a state instance is requested, it returns the cached instance if available; otherwise, it creates, caches, and returns a new instance.

• Custom State Overrides: Supports registering custom subclasses that override default state implementations. When creating a state, it checks if a custom class is registered for the requested default state and instantiates the custom version instead.

• Safe Reflection-based Instantiation: Uses Java reflection to invoke no-argument constructors of state classes dynamically. This allows new states or custom overrides to be added without modifying the factory's internal logic.

• Synchronized Access: Ensures thread safety for cache access and mutation, avoiding concurrency issues during state creation and retrieval.

Key Methods

• createState(Class classType):
  Returns a singleton instance of the requested state class or its custom override. It first looks up a cached instance; if none exists, it creates one via reflection, caches it, and returns it.

• overrideStateCreation(Class subClass):
  Registers a custom subclass to replace one of the known default states. This must be called before any createState invocation to ensure consistent behavior.

• Internal cache management methods (getCacheInstance, setCacheInstance) handle synchronized access to the singleton map.

Example Snippet

public State createState(@NonNull Class classType) {
    Class finalClassType = convertToCustomClass(classType);
    if (finalClassType == null) finalClassType = classType;

    State buildState = getCacheInstance(finalClassType);
    if (buildState == null) {
        Constructor<?> ctor = finalClassType.getConstructor();
        buildState = (State) ctor.newInstance();
        setCacheInstance(finalClassType, buildState);
    }
    return buildState;
}

This snippet shows how the factory creates or retrieves a singleton instance of the requested state or its custom override.

Integration

The State Factory integrates tightly with the parent topic—Finite State Machine Playback—by acting as the authoritative source for all FSM state instances. Its singleton caching mechanism ensures that the FSM player uses consistent state objects across playback sessions, improving performance and reliability.

It complements other subtopics by:

• Enabling Flexible State Management: While the "State Management" subtopic defines concrete state classes and transitions, the State Factory controls how these states are instantiated and reused.

• Supporting Extensibility: By allowing custom state overrides, it enables enhancement or replacement of default FSM behaviors without changing FSM core logic or other components like Ad or Cue Point Management.

• Promoting Decoupling: The FSM player and states rely on the factory for creation, reducing direct dependencies on concrete state constructors and supporting inversion of control.

Overall, the State Factory is a foundational utility that underpins the FSM's modular, extensible design by unifying state instantiation and lifecycle management.

State Creation Flowchart

flowchart TD
    A[Request State Instance] --> B{Is there a custom override?}
    B -->|Yes| C[Use Custom State Class]
    B -->|No| D[Use Default State Class]
    C --> E{Is instance cached?}
    D --> E
    E -->|Yes| F[Return Cached Instance]
    E -->|No| G[Create Instance via Reflection]
    G --> H[Cache Instance]
    H --> F

This flowchart visualizes the process of creating or retrieving FSM state instances in the State Factory. It highlights the decision points for custom overrides and caching to ensure efficient, flexible state management.