Package com.google.common.truth.extensions.proto

Class FieldScope

  • public abstract class FieldScope
extends Object
    An immutable, abstract representation of a set of specific field paths. See FieldScopes for entry points to obtain a FieldScope object.

    A FieldScope is similar in concept to a FieldMask, which is an explicitly enumerated set of specific field paths. A FieldScope is more general, allowing for the description of arbitrary classes of specific field paths to be included or excluded from its definition. For example, given a large protocol buffer with many field definitions, and a single string field named 'x', it is arduous to specify "All fields except 'x'" as a FieldMask. With a FieldScope, it is simply FieldScopes.ignoringFields(MyMessage.X_FIELD_NUMBER).

    All inclusion and exclusion operations on message-type fields are recursive, but may be overridden by subsequent operations. In this way, a complex FieldScope such as: 

    
 FieldScopes.ignoringFields(A.B_FIELD_NUMBER)
     .allowingFieldDescriptors(B.getDescriptor().findFieldByName("flag"))
    ...will match all fields on A, except fields on the message type B, but including B's flag field. Thus, two messages of type A will compare equal even if their sub messages of type B are completely different, so long as the 'flag' fields for each B matches. Because of this, method ordering matters. Generally, exclusions should come after inclusions.

    FieldScopes are not designed to be compact or efficient, trading flexibility of use for runtime efficiency, generally composing themselves as recursive structures. For this reason, it is not recommended to use FieldScope in production code. Prefer to use proper FieldMasks, directly in production code.

    • Method Detail

      • ignoringFields

        public abstract FieldScope ignoringFields​(int firstFieldNumber,
                                          int... rest)
        Returns a FieldScope equivalent to this one, minus all fields defined by the given field numbers.

        Validation of the field numbers is performed when the FieldScope is invoked (typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)). A runtime exception will occur if bad field numbers are encountered.

        The field numbers are ignored recursively on this type. That is, if YourMessage contains another YourMessage somewhere within its subtree, a FieldScope ignoringFields(X) will ignore field number X for all submessages of type YourMessage, as well as for the top-level message.

      • ignoringFields

        public abstract FieldScope ignoringFields​(Iterable<Integer> fieldNumbers)
        Returns a FieldScope equivalent to this one, minus all fields defined by the given field numbers.

        Validation of the field numbers is performed when the FieldScope is invoked (typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)). A runtime exception will occur if bad field numbers are encountered.

        The field numbers are ignored recursively on this type. That is, if YourMessage contains another YourMessage somewhere within its subtree, a FieldScope ignoringFields(X) will ignore field number X for all submessages of type YourMessage, as well as for the top-level message.

      • ignoringFieldDescriptors

        public abstract FieldScope ignoringFieldDescriptors​(Descriptors.FieldDescriptor firstFieldDescriptor,
                                                    Descriptors.FieldDescriptor... rest)
        Returns a FieldScope equivalent to this one, minus all fields matching the given Descriptors.FieldDescriptors.

        The Descriptors.FieldDescriptors are not validated, as that would require scanning the entire protobuf schema recursively from this message type. If a Descriptors.FieldDescriptor is provided which refers to a field that is not part of this message, or any possible recursive submessages, it is silently ignored.

        The field descriptors are also ignored recursively on the message type. That is, if FooMessage.field_bar is ignored, field_bar will be ignored for all submessages of the parent type of type FooMessage.

      • ignoringFieldDescriptors

        public abstract FieldScope ignoringFieldDescriptors​(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
        Returns a FieldScope equivalent to this one, minus all fields defined by the given field numbers.

        The Descriptors.FieldDescriptors are not validated, as that would require scanning the entire protobuf schema recursively from this message type. If a Descriptors.FieldDescriptor is provided which refers to a field that is not part of this message, or any possible recursive submessages, it is silently ignored.

        The field descriptors are also ignored recursively on the message type. That is, if FooMessage.field_bar is ignored, field_bar will be ignored for all submessages of the parent type of type FooMessage.

      • allowingFields

        public abstract FieldScope allowingFields​(int firstFieldNumber,
                                          int... rest)
        Returns a FieldScope equivalent to this one, plus all fields defined by the given field numbers.

        Validation of the field numbers is performed when the FieldScope is invoked (typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)). A runtime exception will occur if bad field numbers are encountered.

        The field numbers are included recursively on this type. That is, if YourMessage contains another YourMessage somewhere within its subtree, a FieldScope allowingFields(X) will include field number X for all submessages of type YourMessage, as well as for the top-level message.

      • allowingFields

        public abstract FieldScope allowingFields​(Iterable<Integer> fieldNumbers)
        Returns a FieldScope equivalent to this one, plus all fields defined by the given field numbers.

        Validation of the field numbers is performed when the FieldScope is invoked (typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)). A runtime exception will occur if bad field numbers are encountered.

        The field numbers are included recursively on this type. That is, if YourMessage contains another YourMessage somewhere within its subtree, a FieldScope allowingFields(X) will include field number X for all submessages of type YourMessage, as well as for the top-level message.

      • allowingFieldDescriptors

        public abstract FieldScope allowingFieldDescriptors​(Descriptors.FieldDescriptor firstFieldDescriptor,
                                                    Descriptors.FieldDescriptor... rest)
        Returns a FieldScope equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptors.

        The Descriptors.FieldDescriptors are not validated, as that would require scanning the entire protobuf schema from this message type. If a Descriptors.FieldDescriptor is provided which refers to a field that is not part of this message, or any possible recursive submessages, it is silently ignored.

        The field descriptors are also included recursively on the message type. That is, if FooMessage.field_bar is included, field_bar will be included for all submessages of the parent type of type FooMessage.

      • allowingFieldDescriptors

        public abstract FieldScope allowingFieldDescriptors​(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
        Returns a FieldScope equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptors.

        The Descriptors.FieldDescriptors are not validated, as that would require scanning the entire protobuf schema from this message type. If a Descriptors.FieldDescriptor is provided which refers to a field that is not part of this message, or any possible recursive submessages, it is silently ignored.

        The field descriptors are also included recursively on the message type. That is, if FooMessage.field_bar is included, field_bar will be included for all submessages of the parent type of type FooMessage.