com.google.common.truth.extensions.proto

Class FieldScope

java.lang.Object

com.google.common.truth.extensions.proto.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 Summary

Methods

Modifier and Type	Method and Description
abstract FieldScope	allowingFieldDescriptors(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor, com.google.protobuf.Descriptors.FieldDescriptor... rest) Returns a FieldScope equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptors.
abstract FieldScope	allowingFields(int firstFieldNumber, int... rest) Returns a FieldScope equivalent to this one, plus all fields defined by the given field numbers.
abstract FieldScope	ignoringFieldDescriptors(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor, com.google.protobuf.Descriptors.FieldDescriptor... rest) Returns a FieldScope equivalent to this one, minus all fields matching the given Descriptors.FieldDescriptors.
abstract FieldScope	ignoringFields(int firstFieldNumber, int... rest) Returns a FieldScope equivalent to this one, minus all fields defined by the given field numbers.

Methods inherited from class java.lang.Object

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

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(java.lang.Object)). 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(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor,
                                  com.google.protobuf.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.

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(java.lang.Object)). 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(com.google.protobuf.Descriptors.FieldDescriptor firstFieldDescriptor,
                                  com.google.protobuf.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.