Package io.github.jspinak.brobot.util.file

package io.github.jspinak.brobot.util.file
File handling utilities for saving and managing automation artifacts.

This package provides comprehensive file management capabilities for the Brobot framework, focusing on saving screenshots, XML documents, and other artifacts generated during automation runs. It includes utilities for filename manipulation, conflict prevention, and organized storage of automation data.

Core Components

SaveToFile Interface

Defines the contract for file saving operations:
  • Folder creation with automatic parent directory handling
  • Image saving with configurable naming strategies
  • XML document persistence for structured data
  • Extensible design for different storage backends

RecorderSaveToFile

Production implementation of SaveToFile:
  • Timestamp-based image naming for chronological ordering
  • Centralized recording folder management
  • Integration with BrobotProperties for configuration
  • Automatic folder structure creation

FilenameAllocator

Thread-safe filename reservation system:
  • Prevents file overwrites in concurrent scenarios
  • Automatic index generation for duplicate names
  • In-memory tracking of reserved filenames
  • Coordination with filesystem checks

FilenameUtils

Low-level filename manipulation utilities:
  • Extension handling (defaulting to PNG)
  • Filename extraction and transformation
  • Simple, stateless operations

Usage Patterns

Recording Automation Sessions


 @Autowired
 private SaveToFile saveToFile;

 // Save screenshot with timestamp
 String filename = saveToFile.saveImage(bufferedImage, "test-action");

 // Save XML report
 saveToFile.saveXML(document, "results.xml");

Preventing Filename Conflicts


 @Autowired
 private FilenameAllocator filenameAllocator;

 // Reserve unique filename
 String uniqueName = filenameAllocator.reserve(baseFolder, "screenshot");
 // Returns: screenshot.png, screenshot_1.png, etc.

Filename Manipulation


 // Add extension if needed
 String pngFile = FilenameUtils.addPngExtension("screenshot");

 // Extract name without extension
 String baseName = FilenameUtils.getFilenameWithoutExtension("image.png");

File Organization

The package supports organized file storage:
  • Timestamp-based folder naming: recordings/{timestamp}/
  • Chronological image naming: {base}-{milliseconds}.png
  • Automatic directory creation
  • Configurable base paths via BrobotProperties

Design Principles

  • Thread Safety: FilenameAllocator uses synchronization for concurrent access
  • Extensibility: SaveToFile interface allows custom implementations
  • Convention over Configuration: PNG as default format, timestamp naming
  • Fail-Safe: Automatic directory creation, conflict prevention

Integration Points

This package integrates with:
  • Recording subsystem for session capture
  • Illustration generation for visual debugging
  • Report generation for test results
  • Mock operation logging

Performance Considerations

  • In-memory filename tracking minimizes disk I/O
  • Buffered writing for large files
  • Lazy directory creation
Since:
1.0.0
See Also:
  • invalid reference 
    io.github.jspinak.brobot.illustratedHistory
  • invalid reference 
    io.github.jspinak.brobot.recording
  • Class
    Description
    FilenameAllocator
    Manages filename reservations to prevent file conflicts during concurrent operations.
    FilenameUtils
    Utility class for common filename manipulation operations.
    RecorderSaveToFile
    Implementation of SaveToFile for recording automation sessions to disk.
    SaveToFile
    Interface for file saving operations supporting various content types.