Package org.a2aproject.sdk.spec

Class FileWithBytes

java.lang.Object
org.a2aproject.sdk.spec.FileWithBytes
All Implemented Interfaces:
FileContent
public final class FileWithBytes extends Object implements FileContent
Represents file content embedded directly as base64-encoded bytes.

FileWithBytes is used when file content needs to be transmitted inline with the message or artifact, rather than requiring a separate download. This is appropriate for:

  • Small files that fit comfortably in a JSON payload
  • Generated content that doesn't exist as a standalone file
  • Content that must be preserved exactly as created
  • Scenarios where URI accessibility is uncertain

The bytes field contains the base64-encoded file content. Decoders should handle the base64 encoding/decoding transparently.

This class uses lazy loading with soft-reference caching to reduce memory pressure: the base64-encoded content is computed on-demand and held via a SoftReference, allowing the JVM to reclaim it under memory pressure. If reclaimed, it is recomputed on next access.

See Also:

  • Constructor Details

    • FileWithBytes

      public FileWithBytes(String mimeType, String name, String bytes)
      Creates a FileWithBytes with pre-encoded base64 content. This is the canonical constructor used by serialization frameworks.
      Parameters:
      mimeType - the MIME type of the file (e.g., "image/png", "application/pdf")
      name - the file name (e.g., "report.pdf", "diagram.png")
      bytes - the base64-encoded file content

    • FileWithBytes

      public FileWithBytes(String mimeType, File file)
      Creates a FileWithBytes by reading the content of the given File. The file name is derived from File.getName().

      The file is validated at construction time to ensure it exists, is readable, is a regular file, and does not exceed the maximum size limit (10485760L bytes).

      The file content is read and base64-encoded on the first call to bytes(), then cached via a soft reference. The cache may be cleared by GC under memory pressure, in which case the file is re-read on the next access.

      Parameters:
      mimeType - the MIME type of the file (e.g., "image/png")
      file - the file whose content will be read and encoded
      Throws:
      IllegalArgumentException - if the file does not exist, is not readable, is not a regular file, or exceeds the maximum size limit
      RuntimeException - if an I/O error occurs while checking the file

    • FileWithBytes

      public FileWithBytes(String mimeType, Path file)
      Creates a FileWithBytes by reading the content of the given Path. The file name is derived from Path.getFileName().

      The file is validated at construction time to ensure it exists, is readable, is a regular file, and does not exceed the maximum size limit (10485760L bytes).

      The file content is read and base64-encoded on the first call to bytes(), then cached via a soft reference. The cache may be cleared by GC under memory pressure, in which case the file is re-read on the next access.

      Parameters:
      mimeType - the MIME type of the file (e.g., "image/png")
      file - the path whose content will be read and encoded
      Throws:
      IllegalArgumentException - if the file does not exist, is not readable, is not a regular file, or exceeds the maximum size limit
      RuntimeException - if an I/O error occurs while checking the file

    • FileWithBytes

      public FileWithBytes(String mimeType, String name, byte[] content)
      Creates a FileWithBytes by base64-encoding the given raw byte array.

      A defensive copy of content is made at construction time, so subsequent mutations to the caller's array have no effect. The copy is base64-encoded on the first call to bytes(), then cached via a soft reference. The cache may be cleared by GC under memory pressure, in which case the encoding is recomputed from the retained copy.

      Parameters:
      mimeType - the MIME type of the file (e.g., "application/pdf")
      name - the file name (e.g., "report.pdf")
      content - the raw file content to be base64-encoded
      Throws:
      NullPointerException - if content is null

  • Method Details

    • mimeType

      public String mimeType()
      Description copied from interface: FileContent
      Returns the MIME type of the file content.
      Specified by:
      mimeType in interface FileContent
      Returns:
      the MIME type (e.g., "image/png", "text/plain", "application/json")

    • name

      public String name()
      Description copied from interface: FileContent
      Returns the file name.
      Specified by:
      name in interface FileContent
      Returns:
      the file name (e.g., "document.pdf", "image.jpg")

    • bytes

      public String bytes()
      Returns the base64-encoded file content.

      The content is computed on the first call and cached via a soft reference. Subsequent calls return the cached value. If the JVM reclaims the cache under memory pressure, the content is recomputed transparently on the next access.

      For instances created from a File or Path, recomputation involves reading the file from disk. Callers in performance-sensitive paths should retain the returned value rather than calling this method repeatedly.

      Returns:
      the base64-encoded file content
      Throws:
      RuntimeException - if an I/O error occurs while reading a file-backed source

    • equals

      public boolean equals(Object o)
      Compares this FileWithBytes to another object for equality.

      Important: This method uses identity-based comparison to avoid triggering potentially expensive I/O operations. Two FileWithBytes instances are considered equal only if they are the same object (reference equality).

      This design choice prevents:

      • Unexpected file I/O during collection operations (HashMap, HashSet, etc.)
      • Performance issues when comparing file-backed instances
      • RuntimeExceptions from I/O errors during equality checks

      If you need to compare the actual content of two FileWithBytes instances, use a separate method or compare the results of bytes() explicitly.

      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare with
      Returns:
      true if this is the same object as o, false otherwise

    • hashCode

      public int hashCode()
      Returns the identity hash code for this FileWithBytes.

      This method uses System.identityHashCode(Object) to avoid triggering I/O operations that would be required to compute a content-based hash code. This ensures that using FileWithBytes instances as keys in HashMap or elements in HashSet remains safe and efficient.

      Overrides:
      hashCode in class Object
      Returns:
      the identity hash code

    • toString

      public String toString()
      Overrides:
      toString in class Object