Annotation Interface ProtoField

@Documented @Retention(RUNTIME) @Target({FIELD,METHOD,PARAMETER,RECORD_COMPONENT,ANNOTATION_TYPE}) public @interface ProtoField
Assigns a Protocol Buffers field number, and optionally a wire representation, to a property.

Field numbers are the identity of a property on the wire; names are never transmitted. A number can be given explicitly, with @ProtoField(3) or @ProtoField(position = 3), or left out, in which case the property takes its number from its position among the message's properties: the first is 1, the second is 2, and so on. A property with no annotation at all is numbered the same way.

Positions derived from order are convenient, and they are also fragile: inserting, removing or reordering a property silently renumbers everything after it, and payloads written by an earlier version are then read back into the wrong properties. Derived numbering suits a message whose writer and readers are deployed together. Anything that outlives a single deployment — stored payloads, a published API, messages on a queue — should number its fields explicitly.

This is prototype API and subject to change.

Since:
3.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    MAX_FIELD_NUMBER
    The highest legal Protocol Buffers field number.
    static final int
    MIN_FIELD_NUMBER
    The lowest legal Protocol Buffers field number.
    static final int
    UNSET_POSITION
    The value of position() that means "take the number from the property's position among the message's properties".

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    position
    The field number.
    ProtoType
    type
    The wire representation to use.
    int
    value
    The field number.

  • Field Details

    • MIN_FIELD_NUMBER

      static final int MIN_FIELD_NUMBER
      The lowest legal Protocol Buffers field number.
      See Also:

    • MAX_FIELD_NUMBER

      static final int MAX_FIELD_NUMBER
      The highest legal Protocol Buffers field number.
      See Also:

    • UNSET_POSITION

      static final int UNSET_POSITION
      The value of position() that means "take the number from the property's position among the message's properties".
      See Also:

  • Element Details

    • value

      @AliasFor(member="position") int value
      The field number. An alias for position(), so @ProtoField(3) and @ProtoField(position = 3) mean the same thing.
      Returns:
      The field number, or UNSET_POSITION to derive it from declaration order
      Default:
      -1

    • position

      @AliasFor(member="value") int position
      The field number. Must be between MIN_FIELD_NUMBER and MAX_FIELD_NUMBER, and must not fall in the range 19000-19999 that Protocol Buffers reserves.

      Left at UNSET_POSITION, the property is numbered by its position among the message's properties, counting from one.

      Returns:
      The field number, or UNSET_POSITION to derive it from declaration order
      Default:
      -1

    • type

      ProtoType type
      The wire representation to use. Defaults to ProtoType.DEFAULT, which picks the representation from the Java type.
      Returns:
      The proto type
      Default:
      DEFAULT