Package io.github.jspinak.brobot.runner.json.utils

Class ObjectCollectionJsonUtils

java.lang.Object
io.github.jspinak.brobot.runner.json.utils.ObjectCollectionJsonUtils
@Component public class ObjectCollectionJsonUtils extends Object
Specialized JSON serialization utility for ObjectCollection in the Brobot framework.

ObjectCollection is a heterogeneous container holding various GUI element types (images, regions, locations, strings, matches, scenes) that serve as action targets. This utility handles the complex serialization challenges arising from the diverse object types and their nested structures, particularly focusing on non-serializable components like OpenCV Mat objects.

Key serialization challenges addressed:

  • Heterogeneous content: Safely serializes different object types (StateImage, StateLocation, StateRegion, StateString) in a single collection
  • Match objects: Delegates to MatchesJsonUtils for proper handling of ActionResult objects that may contain Mat references
  • Scene objects: Extracts only essential metadata (filenames) from Scene objects to avoid serializing large image data
  • Circular references: Prevents infinite recursion when objects reference their parent collections or states

This utility enables critical functionality:

  • Saving collections of GUI elements for offline automation
  • Transmitting element collections between distributed systems
  • Creating test fixtures with predefined element collections
  • Debugging by inspecting serialized element hierarchies

The Map-based approach provides flexibility to customize serialization for each element type while maintaining a consistent structure that can be reliably deserialized back to functional ObjectCollection instances.

Since:
1.0
See Also:

  • Constructor Details

  • Method Details

    • objectCollectionToMap

      public Map<String,Object> objectCollectionToMap(ObjectCollection collection)
      Converts ObjectCollection to a Map representation for controlled serialization.

      This method transforms the complex ObjectCollection structure into a simplified Map that can be safely serialized to JSON. Each element type is handled according to its specific serialization requirements:

      Serialization strategy by type:

      • State elements: StateLocations, StateImages, StateRegions, and StateStrings are included directly as they are inherently serializable
      • Matches: Delegated to MatchesJsonUtils.matchesToMap() to handle complex ActionResult objects with potential Mat references
      • Scenes: Reduced to filename metadata only, avoiding serialization of large image data stored in Pattern objects

      This selective approach ensures that:

      • All essential configuration data is preserved
      • Non-serializable components are safely excluded
      • The resulting JSON remains compact and readable
      • Deserialization can reconstruct functional collections
      Parameters:
      collection - The ObjectCollection to convert
      Returns:
      Map containing serializable representations of all collection elements

    • objectCollectionToJson

      public String objectCollectionToJson(ObjectCollection collection) throws ConfigurationException
      Serializes ObjectCollection to a JSON string representation.

      This method provides safe JSON serialization for ObjectCollection instances, handling all the complexity of heterogeneous element types and nested structures. The resulting JSON preserves all necessary data for reconstructing the collection while avoiding serialization pitfalls.

      Usage example: 

      
 ObjectCollection collection = new ObjectCollection.Builder()
     .withImages(stateImage1, stateImage2)
     .withRegions(region1, region2)
     .withMatches(previousResults)
     .build();

 String json = objectCollectionJsonUtils.objectCollectionToJson(collection);
 // Use for persistence, transmission, or debugging

      The serialization process automatically handles:

      • Complex object graphs with proper reference handling
      • Exclusion of non-serializable fields
      • Optimization of large data structures like Scenes
      Parameters:
      collection - The ObjectCollection to serialize
      Returns:
      JSON string representation of the collection
      Throws:
      ConfigurationException - if serialization fails

    • deepCopy

      public ObjectCollection deepCopy(ObjectCollection collection) throws ConfigurationException
      Creates a deep copy of ObjectCollection through serialization.

      This method implements a robust deep copy mechanism that ensures complete independence between the original and copied ObjectCollection. This is essential for scenarios where collections need to be modified without affecting the original, such as in parallel processing or state management.

      Deep copy characteristics:

      • All element lists are independently copied
      • Nested objects like Matches are fully cloned
      • No references are shared between original and copy
      • Scene references are preserved through filename metadata

      Common use cases:

      • Creating variants of element collections for testing
      • Preserving original collections before modifications
      • Distributing collections across parallel execution threads
      • Implementing undo/redo functionality

      Note: While the copy is independent, Scene objects will need to reload their image data from disk as Mat objects are not serialized.

      Parameters:
      collection - The ObjectCollection to copy
      Returns:
      A new ObjectCollection instance with no shared references
      Throws:
      ConfigurationException - if the copy operation fails