iB86/.qoder/quests/network-state-manager-improvement.md

# Network State Manager Improvement Design

## Overview

The current NetworkStateManager implementation does not support interrupting notifications. When a notification popup is still active and a new notification with higher priority arrives, the system cannot interrupt the previous notification. The requirement is to implement a notification interruption mechanism where higher priority notifications can preempt lower priority ones.

## Current Architecture Analysis

### NetworkStateManager Components

The current implementation consists of several key components:

1. **NetworkStateManager**: Main manager class that handles network state changes and notification display
2. **NetworkStateMonitor/SimpleNetworkStateManager**: Monitors network state changes
3. **NotificationManager**: Manages notification display and hiding
4. **CommonNotificationActivity**: The actual notification UI activity

### Current Notification Flow

```mermaid
sequenceDiagram
    participant NSM as NetworkStateManager
    participant NM as NotificationManager
    participant CNA as CommonNotificationActivity
    NSM->>NM: showNotification()
    NM->>NM: Check if activity showing
    NM->>CNA: Start notification activity
    CNA->>CNA: Display notification for duration
    CNA->>NM: Broadcast on close
```

### Limitation Analysis

The current implementation has the following limitations:
1. Notifications cannot be interrupted - if one is showing, new notifications are ignored
2. No priority mechanism for different notification types
3. No queue management for pending notifications

## Improved Architecture Design

### Design Goals

1. Support notification interruption based on priority
2. Maintain backward compatibility
3. Ensure proper resource cleanup
4. Handle notification queue management

### Enhanced Notification Flow

```mermaid
sequenceDiagram
    participant NSM as NetworkStateManager
    participant ENM as EnhancedNotificationManager
    participant CNA as CommonNotificationActivity
    NSM->>ENM: showNotification(priority, ...)
    ENM->>ENM: Check current notification
    alt Higher priority
        ENM->>CNA: Interrupt current notification
        ENM->>CNA: Show new notification
    else Same or lower priority
        ENM->>ENM: Queue notification
    end
```

### Component Modifications

#### 1. Notification Priority Enum

A new priority enumeration will be introduced:

| Priority | Value | Description |
|----------|-------|-------------|
| LOW | 0 | Low priority notifications |
| NORMAL | 1 | Normal priority notifications |
| HIGH | 2 | High priority notifications |
| URGENT | 3 | Urgent notifications that can interrupt any other |

#### 2. Enhanced Notification Manager

The NotificationManager will be enhanced with the following capabilities:

1. **Priority-based interruption**: Higher priority notifications can interrupt lower priority ones
2. **Notification queue**: Pending notifications will be queued based on priority
3. **Current notification tracking**: Track the currently displayed notification's priority

#### 3. Notification Data Structure

A new data structure will be created to hold notification information:

```java
class NotificationRequest {
    NotificationType type;
    String message;
    int iconResId;
    int durationSeconds;
    String soundPath;
    NotificationPriority priority;
}
```

## Implementation Plan

### Phase 1: Core Enhancement

1. **Add NotificationPriority enum**:
   - Define priority levels (LOW, NORMAL, HIGH, URGENT)
   - Associate with NotificationType for default priorities

2. **Enhance NotificationManager**:
   - Add priority parameter to showNotification methods
   - Implement interruption logic
   - Add notification queue management

3. **Modify NetworkStateManager**:
   - Update notification calls to include priority
   - Set appropriate priorities for different network events

### Phase 2: Queue Management

1. **Implement notification queue**:
   - FIFO for same priority notifications
   - Priority-based for different priority notifications

2. **Add queue processing logic**:
   - Process next notification when current one closes
   - Handle queue cleanup

### Phase 3: Testing and Validation

1. **Unit tests**:
   - Test interruption scenarios
   - Test queue management
   - Test backward compatibility

2. **Integration tests**:
   - Test with actual network state changes
   - Validate priority-based behavior

## API Changes

### New Enum: NotificationPriority

```java
public enum NotificationPriority {
    LOW(0),
    NORMAL(1),
    HIGH(2),
    URGENT(3);
    
    private final int value;
    
    NotificationPriority(int value) {
        this.value = value;
    }
    
    public int getValue() {
        return value;
    }
}
```

### Enhanced NotificationManager Methods

```java
// New methods with priority support
public void showNotification(NotificationType type, String message, int iconResId, 
                           int durationSeconds, NotificationPriority priority);

public void showNotification(NotificationType type, String message, int iconResId, 
                           int durationSeconds, String soundPath, NotificationPriority priority);
```

### Updated NetworkStateManager

The NetworkStateManager will use appropriate priorities for different network events:
- NETWORK_LOST: HIGH priority
- NETWORK_CONNECTED: NORMAL priority
- Other events: As appropriate

## Backward Compatibility

To maintain backward compatibility:
1. Existing method signatures will be preserved
2. Default priority (NORMAL) will be used for existing calls
3. All existing functionality will continue to work as before

## Testing Strategy

### Unit Tests

1. **Interruption Tests**:
   - Test that high priority notifications interrupt lower priority ones
   - Test that same priority notifications do not interrupt
   - Test urgent notifications interrupt any other

2. **Queue Management Tests**:
   - Test notification queuing with different priorities
   - Test FIFO behavior for same priority notifications
   - Test queue processing when notifications close

### Integration Tests

1. **Network State Change Tests**:
   - Simulate network loss and connection with different timing
   - Validate that urgent network notifications interrupt others
   - Verify proper notification display and cleanup

## Conclusion

This design addresses the requirement for notification interruption in the NetworkStateManager by introducing a priority-based notification system. The solution maintains backward compatibility while adding the necessary functionality to handle urgent notifications that can preempt existing ones. The implementation is modular and can be extended for future requirements.