Annotation Interface Upcast

@Documented @Retention(RUNTIME) @Target(METHOD) @Cast(revisionDelta=1) @Repeatable(UpcastRepeatable.class) public @interface Upcast
Declares a method that transforms serialized data from one revision to the next during deserialization.

An upcaster is selected by the serialized object's type and revision. After it has been applied, the caster chain continues with the resulting type and revision until no matching upcaster remains.

Method signature

An upcaster method may declare zero or more supported parameters in any order:

  • the intermediate payload value, such as an ObjectNode;
  • the corresponding Data;
  • the source SerializedMessage, when the input is a message;
  • the message Metadata, when the input is a message.

Metadata may therefore be injected alongside the payload or Data. Upcasting also applies to non-message data, such as snapshots, key-value entries, and documents. If no message context is available, a Metadata parameter causes deserialization to fail unless the parameter has an annotation whose simple name is Nullable. A nullable parameter receives null; Kotlin nullable parameter types are recognized as well.

Metadata result

Returning Metadata replaces the complete message metadata while leaving the payload unchanged and advancing its revision by one. Use methods such as Metadata.with(Metadata) or Metadata.with(Object, Object) to retain existing entries. The original SerializedMessage is not mutated. 

@Upcast(type = "com.example.UserCreated", revision = 0)
Metadata addTenant(Metadata metadata) {
    return metadata.with("tenant", "default");
}

A Metadata return type requires message input, even if a metadata parameter is nullable, because non-message data has nowhere to store the result. Returning null is not supported.

Upcaster methods should be side-effect-free and deterministic.

Spring Integration: Any Spring bean containing methods annotated with @Upcast is automatically discovered and registered with the serializer at startup.

See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    int
    revision
    The revision number of the input type this method handles.
    String
    type
    The fully qualified type name this upcaster applies to (e.g., the original serialized class name).

  • Element Details

    • type

      String type
      The fully qualified type name this upcaster applies to (e.g., the original serialized class name).

    • revision

      int revision
      The revision number of the input type this method handles.

      This is the revision the method accepts and transforms from.