Package io.github.flink.gcp.connector.spanner.sink

Class FailedMutation

java.lang.Object
io.github.flink.gcp.connector.spanner.sink.FailedMutation
All Implemented Interfaces:
FailedElement
@Public public final class FailedMutation extends Object implements FailedElement
A single mutation that terminally failed to be applied to Spanner, as passed to a FailureHandler<FailedMutation>.

Carries the Mutation the serializer produced rather than the original record: the sink writer is stateless and retains only mutations, so by the time the service rejects one the original record object no longer exists. When serialization itself failed, getMutation() and getTable() are null.

What the payload bytes are, and why

getPayloadBytes() is the Java-serialized Mutation, recovered with an ObjectInputStream against the same client library. It is not a protobuf, and that is not a choice: the Spanner client library exposes no public route from a Mutation to its wire form — Mutation.toProtoAndReturnRandomMutation, Value.toProto(), Key.toProto() and KeySet.appendToProto are all package-private (checked against google-cloud-spanner 6.119.0). Nor can the debug rendering stand in: Mutation.toString() truncates every string value at 36 characters, so it would hand a dead-letter consumer a payload that looks complete and is not. Java serialization is the one non-lossy encoding the public API offers, and Mutation, Value, Key and KeySet each declare a serialVersionUID, so it is an affordance the library maintains rather than an accident.

A handler that wants the mutation itself should take FailureHandler<FailedMutation> and read getMutation(); the bytes exist for the cross-connector DeadLetterQueue view, which sees only FailedElement.

Instances are created by the sink and are not serializable.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    describeDestination()
    Returns the destination as projects/P/instances/I/databases/D/tables/T, or without the table segment when the record could not be serialized.
    Throwable
    getCause()
    Returns the underlying failure, or null when none is available.
    String
    getConnector()
    Returns the connector that produced the failure, as a lower-case identifier ( "bigquery", "bigtable", "cloudtasks", "pubsub", "spanner") — stable, so dead-letter consumers can key on it.
    DatabaseDestination
    getDatabase()
    Returns the database the mutation was routed to.
    String
    getErrorMessage()
    Returns the failure description.
    com.google.cloud.spanner.Mutation
    getMutation()
    Returns the mutation the serializer produced, or null when the record could not be serialized in the first place.
    com.google.protobuf.ByteString
    getPayloadBytes()
    Returns the Java-serialized mutation — see the class documentation for why it is not a protobuf — or null when serialization itself failed.
    String
    getTable()
    Returns the table the mutation applies to, or null when the record could not be serialized.
    static FailedMutation
    of(DatabaseDestination database, com.google.cloud.spanner.Mutation mutation, String errorMessage, Throwable cause)
    Creates a failed mutation.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • of

      public static FailedMutation of(DatabaseDestination database, @Nullable com.google.cloud.spanner.Mutation mutation, String errorMessage, @Nullable Throwable cause)
      Creates a failed mutation. Intended for the sink implementation (and tests of custom handlers).
      Parameters:
      database - the database the mutation was routed to
      mutation - the mutation, or null when serialization itself failed
      errorMessage - the failure description
      cause - the underlying failure, or null
      Returns:
      the failed mutation

    • getDatabase

      public DatabaseDestination getDatabase()
      Returns the database the mutation was routed to.

    • getMutation

      @Nullable public com.google.cloud.spanner.Mutation getMutation()
      Returns the mutation the serializer produced, or null when the record could not be serialized in the first place.

    • getTable

      @Nullable public String getTable()
      Returns the table the mutation applies to, or null when the record could not be serialized.

    • getConnector

      public String getConnector()
      Description copied from interface: FailedElement
      Returns the connector that produced the failure, as a lower-case identifier ( "bigquery", "bigtable", "cloudtasks", "pubsub", "spanner") — stable, so dead-letter consumers can key on it.
      Specified by:
      getConnector in interface FailedElement

    • describeDestination

      public String describeDestination()
      Returns the destination as projects/P/instances/I/databases/D/tables/T, or without the table segment when the record could not be serialized.
      Specified by:
      describeDestination in interface FailedElement

    • getPayloadBytes

      @Nullable public com.google.protobuf.ByteString getPayloadBytes()
      Returns the Java-serialized mutation — see the class documentation for why it is not a protobuf — or null when serialization itself failed.
      Specified by:
      getPayloadBytes in interface FailedElement

    • getErrorMessage

      public String getErrorMessage()
      Description copied from interface: FailedElement
      Returns the failure description. It is always present, even when FailedElement.getCause() is null, and it is the detail that FailureHandler.failJob() raises and FailureHandler.logAndDrop() logs.
      Specified by:
      getErrorMessage in interface FailedElement

    • getCause

      @Nullable public Throwable getCause()
      Description copied from interface: FailedElement
      Returns the underlying failure, or null when none is available.
      Specified by:
      getCause in interface FailedElement

    • toString

      public String toString()
      Overrides:
      toString in class Object