Package org.a2aproject.sdk.grpc.mapper

Interface A2ACommonFieldMapper

All Known Implementing Classes:
A2ACommonFieldMapperImpl
public interface A2ACommonFieldMapper
Common field mapping utilities shared across all mappers.

Provides reusable conversion methods for common protobuf ↔ domain transformations:

  • Empty string → null conversion (protobuf optional string defaults)
  • Timestamp conversions (OffsetDateTime ↔ Protobuf Timestamp, Instant ↔ millis)
  • Metadata conversions (Map ↔ Protobuf Struct)
  • Empty list → null conversion (protobuf repeated field defaults)
  • Zero/false → null conversion (protobuf optional numeric/bool defaults)
  • Enum → null conversion (protobuf UNSPECIFIED/UNKNOWN handling)

  • Field Details

  • Method Details

    • emptyToNull

      default String emptyToNull(String value)
      Converts protobuf empty strings to null for optional fields.

      Protobuf optional strings return "" when unset, but domain models use null. Use this with @Mapping(qualifiedByName = "emptyToNull").

      Parameters:
      value - the protobuf string value
      Returns:
      null if empty/null, otherwise the value

    • requireNonEmpty

      default String requireNonEmpty(String value)
      Validates that a required string field is not null or empty.

      Throws an exception if the protobuf string is null or empty. Use this with @Mapping(qualifiedByName = "requireNonEmpty").

      Parameters:
      value - the protobuf string value
      Returns:
      the value if not null/empty
      Throws:
      IllegalArgumentException - if value is null or empty

    • nullToEmpty

      default String nullToEmpty(String value)
      Converts null strings to empty strings for protobuf.

      Domain models use null for optional fields, but protobuf uses "". Use this with @Mapping(qualifiedByName = "nullToEmpty").

      Parameters:
      value - the domain string value
      Returns:
      "" if null, otherwise the value

    • offsetDateTimeToProtoTimestamp

      default com.google.protobuf.Timestamp offsetDateTimeToProtoTimestamp(OffsetDateTime dateTime)
      Converts domain OffsetDateTime to protobuf Timestamp.

      Use this with @Mapping(qualifiedByName = "offsetDateTimeToProtoTimestamp").

      Parameters:
      dateTime - the domain OffsetDateTime
      Returns:
      protobuf Timestamp, or default instance if input is null

    • protoTimestampToOffsetDateTime

      default OffsetDateTime protoTimestampToOffsetDateTime(com.google.protobuf.Timestamp timestamp)
      Converts protobuf Timestamp to domain OffsetDateTime (UTC).

      Use this with @Mapping(qualifiedByName = "protoTimestampToOffsetDateTime").

      Parameters:
      timestamp - the protobuf Timestamp
      Returns:
      OffsetDateTime in UTC, or null if input is null/default

    • emptyListToNull

      default <T> List<T> emptyListToNull(List<T> list)
      Converts empty lists to null for optional list fields.

      Protobuf repeated fields return empty list when unset, but domain models may use null. Use this with @Mapping(qualifiedByName = "emptyListToNull").

      Parameters:
      list - the protobuf list
      Returns:
      null if empty/null, otherwise the list

    • mapToStruct

      default com.google.protobuf.Struct mapToStruct(Map<String,Object> map)
      Converts domain Map to protobuf Struct (generic conversion).

      Used for any Map<String, Object> field that maps to protobuf Struct (header, params, etc.). Use this with @Mapping(qualifiedByName = "mapToStruct").

      Parameters:
      map - the domain map
      Returns:
      protobuf Struct, or default instance if input is null

    • structToMap

      default Map<String,Object> structToMap(com.google.protobuf.Struct struct)
      Converts protobuf Struct to domain Map (generic conversion).

      Used for any protobuf Struct field that maps to Map<String, Object> (header, params, etc.). Use this with @Mapping(qualifiedByName = "structToMap").

      Parameters:
      struct - the protobuf Struct
      Returns:
      domain Map (may be null for empty Struct)

    • objectToValue

      default com.google.protobuf.Value objectToValue(Object value)
      Converts a Java Object to protobuf Value.

      Supports String, Number, Boolean, Map, List types, and null. Used for struct conversion and arbitrary JSON data.

      Parameters:
      value - the Java object
      Returns:
      protobuf Value

    • valueToObject

      default Object valueToObject(com.google.protobuf.Value value)
      Converts protobuf Value to Java Object.

      Returns appropriate Java type based on Value's kind:

      • STRUCT_VALUE -> Map<String, Object>
      • LIST_VALUE -> List<Object>
      • BOOL_VALUE -> Boolean
      • NUMBER_VALUE -> Double
      • STRING_VALUE -> String
      • NULL_VALUE -> null
      Used for struct conversion and arbitrary JSON data.
      Parameters:
      value - the protobuf Value
      Returns:
      Java object (String, Double, Boolean, Map, List, or null)

    • listToListValue

      default com.google.protobuf.ListValue listToListValue(List<Object> list)
      Converts Java List to protobuf ListValue.

      Used for struct conversion and arbitrary JSON data.

      Parameters:
      list - the Java list
      Returns:
      protobuf ListValue

    • metadataToProto

      default com.google.protobuf.Struct metadataToProto(Map<String,Object> metadata)
      Converts domain metadata Map to protobuf Struct.

      Used for metadata fields in Artifact, Message, Task, and Events. Use this with @Mapping(qualifiedByName = "metadataToProto").

      Parameters:
      metadata - the domain metadata map
      Returns:
      protobuf Struct, or default instance if input is null

    • metadataFromProto

      default Map<String,Object> metadataFromProto(com.google.protobuf.Struct struct)
      Converts protobuf Struct to domain metadata Map.

      Used for metadata fields in Artifact, Message, Task, and Events. Use this with @Mapping(qualifiedByName = "metadataFromProto").

      Parameters:
      struct - the protobuf Struct
      Returns:
      domain metadata Map (may be null for empty Struct)

    • zeroToNull

      default Integer zeroToNull(int value)
      Converts protobuf int to Integer, treating 0 as null (unset).

      Protobuf optional int32 fields default to 0 when unset, but domain models use null. Use this with @Mapping(qualifiedByName = "zeroToNull").

      Parameters:
      value - the protobuf int value
      Returns:
      Integer or null if value is 0

    • intToIntegerOrNull

      default Integer intToIntegerOrNull(int value)
      Converts protobuf int to Integer, preserving all values including 0.

      Unlike zeroToNull, this method preserves 0 values, allowing compact constructor validation to catch invalid values (e.g., pageSize=0 must fail validation). For truly optional fields where 0 means "unset", use zeroToNull instead. Use this with @Mapping(qualifiedByName = "intToIntegerOrNull").

      Parameters:
      value - the protobuf int value
      Returns:
      Integer (never null for primitive int input)

    • zeroLongToNull

      default Long zeroLongToNull(long value)
      Converts protobuf long to Long, treating 0 as null (unset).

      Protobuf optional int64 fields default to 0 when unset, but domain models use null. Use this with @Mapping(qualifiedByName = "zeroLongToNull").

      Parameters:
      value - the protobuf long value
      Returns:
      Long or null if value is 0

    • falseToNull

      default Boolean falseToNull(boolean value)
      Converts protobuf bool to Boolean, treating false as null (unset).

      Protobuf optional bool fields default to false when unset, but domain models use null. Use this with @Mapping(qualifiedByName = "falseToNull").

      Parameters:
      value - the protobuf bool value
      Returns:
      Boolean or null if value is false

    • instantToMillis

      default long instantToMillis(Instant instant)
      Converts domain Instant to protobuf milliseconds-since-epoch (int64).

      Returns 0 if input is null (protobuf default for unset int64). Use this with @Mapping(qualifiedByName = "instantToMillis").

      Parameters:
      instant - the domain Instant
      Returns:
      milliseconds since epoch, or 0 if null

    • millisToInstant

      default Instant millisToInstant(long millis)
      Converts protobuf milliseconds-since-epoch (int64) to domain Instant.

      Returns null if input is 0 (protobuf default for unset field). Throws InvalidParamsError for negative values (invalid timestamps). Use this with @Mapping(qualifiedByName = "millisToInstant").

      Parameters:
      millis - milliseconds since epoch
      Returns:
      domain Instant, or null if millis is 0
      Throws:
      InvalidParamsError - if millis is negative

    • instantToProtoTimestamp

      default com.google.protobuf.Timestamp instantToProtoTimestamp(Instant instant)
      Converts domain Instant to protobuf Timestamp.

      Use this with @Mapping(qualifiedByName = "instantToProtoTimestamp").

      Parameters:
      instant - the domain Instant
      Returns:
      protobuf Timestamp, or default instance if input is null

    • protoTimestampToInstant

      default Instant protoTimestampToInstant(com.google.protobuf.Timestamp timestamp)
      Converts protobuf Timestamp to domain Instant.

      Use this with @Mapping(qualifiedByName = "protoTimestampToInstant").

      Parameters:
      timestamp - the protobuf Timestamp
      Returns:
      Instant, or null if input is null/default

    • taskStateOrNull

      default TaskState taskStateOrNull(TaskState state)
      Converts protobuf TaskState to domain TaskState, treating UNSPECIFIED as null.

      Protobuf enums default to UNSPECIFIED (0 value) when unset, which maps to null for optional fields. However, UNRECOGNIZED (invalid enum values from JSON) throws InvalidParamsError for proper validation. Use this with @Mapping(qualifiedByName = "taskStateOrNull").

      Parameters:
      state - the protobuf TaskState
      Returns:
      domain TaskState or null if UNSPECIFIED
      Throws:
      InvalidParamsError - if state is UNRECOGNIZED (invalid enum value)