Efficient State Management with StateHandler in Kotlin

Why We Need StateHandler

State management is crucial in applications that involve dynamic data updates, such as bookmarking, media playback, and download tracking. Without a structured approach, managing these states can lead to inconsistencies, redundant updates, and increased complexity. The StateHandler class is designed to address these challenges by centralizing state management, synchronizing operations efficiently, and ensuring that only necessary updates are applied.

As applications grow in complexity, manually managing these state changes can become error-prone and difficult to maintain. The StateHandler provides a robust solution by keeping track of different operations in a structured manner, ensuring smooth interactions between user actions and the underlying data. By leveraging Kotlin's coroutines and StateFlow, StateHandler ensures efficient and reactive state management, reducing the risk of data mismatches or unnecessary reprocessing. This use case can be applied to any media application, such as YouTube or YouTube Music, for effective state management.

Overview of StateHandler

The StateHandler class is responsible for:

• Maintaining a map of operations associated with each entity (identified by UUID).
• Persisting media playback positions using DBHelper.
• Updating operations based on download status changes.
• Merging network results with the current operation state.
• Applying operations to modify list of entity data.
• Managing various entity operations efficiently.
• Pruning previous media operations when a new media item starts playing.
• Ensuring that state updates are reactive and efficient.

Core Components

Properties

The StateHandler class is responsible for:

• Maintaining a map of operations associated with each entity (identified by UUID).
• Persisting media playback positions using DBHelper.
• Updating operations based on download status changes.
• Merging network results with the current operation state.
• Applying operations to modify list of entity data.
• Managing various entity operations efficiently.
• Pruning previous media operations when a new media item starts playing.
• Ensuring that state updates are reactive and efficient.

Properties

@Singleton
class StateHandler @Inject constructor(
    private val operationHandler: OperationHandler,
    private val dbHelper: DBHelper,
    @AppScopeJobQualifier private val job: Job,
) {
    private val coroutineScope = CoroutineScope(Dispatchers.IO + job)
    private val _operationsMap = MutableStateFlow<Map<UUID, Set<Operation>>>(emptyMap())
    val operationsMap = _operationsMap.asStateFlow()

...
}        

• operationHandler: Handles logic for different operations.
• dbHelper: Interacts with the database for persisting data.
• job: A coroutine scope job for managing background tasks. It is bound to the application's lifecycle, meaning when the application is destroyed, the job is also canceled. This ensures proper cleanup and prevents memory leaks by automatically stopping ongoing operations.
• operationsMap: A StateFlow holding operations mapped to entities, ensuring state changes propagate reactively.

Initialization

During initialization, StateHandler synchronizes stored media playback positions and downloads with the current state:

init {
    coroutineScope.launch {
        dbHelper.audioRememberPositionDao().getAllAudioPositions().forEach {
            updateOperation(
                it.audioUuid,
                Media.StopPosition(it.stopPosition, it.totalDuration)
            )
        }
    }
    coroutineScope.launch {
        dbHelper.downloadDao().getDownloadEntitiesStatus().collect {
            val updates = it.filter { (uuid, status, path) ->
                val existingOperation = operationsMap.value[uuid].orEmpty()
                val isDownloadChanged = existingOperation.isEmpty() || isDownloadChanged //check for downloadChange
            }
            updates.forEach { (uuid, status, path) ->
                updateOperation(uuid, Operation.Download(status, path))
            }
        }
    }
}        

This ensures that any persisted media playback positions and download statuses are properly reflected in the application’s state, reducing unnecessary re-fetching and inconsistencies.

Handling State Updates

Updating an Operation

The updateOperation method is central to updating state changes:

fun updateOperation(uuid: UUID, operation: Operation) {
    val currentMap = if (operation is Media.Playing) {
        pruneMediaOperations(playingMediaUUID).also {
            playingMediaUUID = uuid
        }
    } else operationsMap.value.toMutableMap()
    val currentOperations = currentMap.getOrPut(uuid) { setOf() }.toMutableSet()
    currentOperations.removeIf { it::class == operation::class }
    currentOperations.add(operation)
    currentMap[uuid] = currentOperations
    _operationsMap.update { currentMap }
}        

This method ensures that new operations replace previous instances of the same type while maintaining other existing operations for that UUID, keeping state updates concise and meaningful.

Managing Media Playback

Handling media playback requires ensuring only one media item is marked as playing at a time:

private fun pruneMediaOperations(uuid: UUID): MutableMap<UUID, Set<Operation>> {
    val currentMap = operationsMap.value.toMutableMap()
    currentMap[uuid] = currentMap[uuid]?.map {
        if (it is Media.Playing) Media.StopPosition(it.media.currentPosition, it.media.audioDuration)
        else it
    }?.toSet().orEmpty()
    return currentMap
}        

This replaces a Playing operation with a StopPosition operation when playback stops or switches to another media item, ensuring accurate media state transitions.

Synchronizing with List of Entities

To merge a list of entities with existing states, StateHandler provides the following function:

private fun Flow<List<Entity>>.mergeListWithOtherStates() = combine(
    this, operationsMap
) { data, syncData ->
    data.map { entity ->
        val operations = operationsMap[entity.uuid].orEmpty()
        if (!needsUpdate(entity, operations)) entity else entity.modifyDataWithOperation(operations)
    }
}.distinctUntilChanged()        

This function ensures that entities retrieved from a data source incorporate the latest operations from operationsMap, maintaining consistency between stored states and fetched data.

Checking If Updates Are Needed

Before modifying an entity with operations, StateHandler verifies if an update is necessary to avoid redundant updates:

private fun needsUpdate(entity: Entity, operations: Set<Operation>): Boolean {
    if (operations.isEmpty()) return false
    return operationHandler.needsUpdate(entity, operations)
}        

This check ensures efficient state updates by preventing unnecessary modifications when no changes are required.

Supported Operations

The StateHandler works with various operations, including:

sealed class Operation {
    data class Bookmark(val isBookmarked: Boolean) : Operation()
    data class Download(
        val downloadStatus: String? = null,
        val audioPath: String? = null,
    ) : Operation()
    
    sealed class Media : Operation() {
        class StopPosition(val stopPosition: Long?, val totalDuration: Long) : Media()
        class Playing(val media: MediaStatus) : Media()
    }
    
    // More operations can be added here as needed.
}        

These operations encapsulate changes related to bookmarking, downloads, and media playback, with the flexibility to extend support for additional operations.

Conclusion

The StateHandler class is a powerful solution for managing state in a structured and efficient way. By leveraging Kotlin’s coroutines, Flows, and a clean separation of concerns, it provides a robust foundation for stateful operations in an application. Whether tracking media playback, synchronizing fetched data, or managing download statuses, StateHandler simplifies state management while keeping the logic maintainable and scalable.

Would you like to see a real-world implementation of StateHandler in action? Let us know in the comments!