extensions/proto/src/main/java/com/google/common/truth/extensions/proto/FieldScopeLogic.java - platform/external/truth - Git at Google

 /*
  * Copyright (c) 2016 Google, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package com.google.common.truth.extensions.proto;

 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.truth.extensions.proto.FieldScopeUtil.join;

 import com.google.common.base.Joiner;
 import com.google.common.base.Optional;
 import com.google.common.base.Verify;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSet;
 import com.google.errorprone.annotations.ForOverride;
 import com.google.protobuf.Descriptors.Descriptor;
 import com.google.protobuf.Descriptors.FieldDescriptor;
 import com.google.protobuf.ExtensionRegistry;
 import com.google.protobuf.Message;
 import com.google.protobuf.TypeRegistry;
 import java.util.List;

 /**
  * Implementations of all variations of {@link FieldScope} logic.
  *
  * <p>{@code FieldScopeLogic} is the abstract base class which provides common functionality to all
  * sub-types. There are two classes of sub-types:
  *
  * <ul>
  *   <li>Concrete subtypes, which implements specific rules and perform no delegation.
  *   <li>Compound subtypes, which combine one or more {@code FieldScopeLogic}s with specific
  *       operations.
  * </ul>
  */
 abstract class FieldScopeLogic implements FieldScopeLogicContainer<FieldScopeLogic> {

   /**
    * Returns whether the given field is included in this FieldScopeLogic, along with whether it's
    * included recursively or not.
    */
   abstract FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId);

   /** Returns whether the given field is included in this FieldScopeLogic. */
   final boolean contains(Descriptor rootDescriptor, SubScopeId subScopeId) {
     return policyFor(rootDescriptor, subScopeId).included();
   }

   /**
    * Returns a {@code FieldScopeLogic} to handle the message pointed to by this descriptor.
    *
    * <p>Subclasses which can return non-recursive {@link FieldScopeResult}s must override {@link
    * #subScopeImpl} to implement those cases.
    */
   @Override
   public final FieldScopeLogic subScope(Descriptor rootDescriptor, SubScopeId subScopeId) {
     FieldScopeResult result = policyFor(rootDescriptor, subScopeId);
     if (result.recursive()) {
       return result.included() ? all() : none();
     } else {
       return subScopeImpl(rootDescriptor, subScopeId);
     }
   }

   /**
    * Returns {@link #subScope} for {@code NONRECURSIVE} results.
    *
    * <p>Throws an {@link UnsupportedOperationException} by default. Subclasses which can return
    * {@code NONRECURSIVE} results must override this method.
    */
   @ForOverride
   FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
     throw new UnsupportedOperationException("subScopeImpl not implemented for " + getClass());
   }

   /**
    * Returns an accurate description for debugging purposes.
    *
    * <p>Compare to {@link FieldScope#usingCorrespondenceString(Optional)}, which returns a beautiful
    * error message that makes as much sense to the user as possible.
    *
    * <p>Abstract so subclasses must implement.
    */
   @Override
   public abstract String toString();

   @Override
   public void validate(
       Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {}

   private static boolean isEmpty(Iterable<?> container) {
     boolean isEmpty = true;
     for (Object element : container) {
       checkNotNull(element);
       isEmpty = false;
     }

     return isEmpty;
   }

   // TODO(user): Rename these 'ignoring' and 'allowing' methods to 'plus' and 'minus', or
   // something else that doesn't tightly couple FieldScopeLogic to the 'ignore' concept.
   FieldScopeLogic ignoringFields(Iterable<Integer> fieldNumbers) {
     if (isEmpty(fieldNumbers)) {
       return this;
     }
     return and(
         this,
         new NegationFieldScopeLogic(new FieldNumbersLogic(fieldNumbers, /* isRecursive = */ true)));
   }

   FieldScopeLogic ignoringFieldDescriptors(Iterable<FieldDescriptor> fieldDescriptors) {
     if (isEmpty(fieldDescriptors)) {
       return this;
     }
     return and(
         this,
         new NegationFieldScopeLogic(
             new FieldDescriptorsLogic(fieldDescriptors, /* isRecursive = */ true)));
   }

   FieldScopeLogic allowingFields(Iterable<Integer> fieldNumbers) {
     if (isEmpty(fieldNumbers)) {
       return this;
     }
     return or(this, new FieldNumbersLogic(fieldNumbers, /* isRecursive = */ true));
   }

   FieldScopeLogic allowingFieldsNonRecursive(Iterable<Integer> fieldNumbers) {
     if (isEmpty(fieldNumbers)) {
       return this;
     }
     return or(this, new FieldNumbersLogic(fieldNumbers, /* isRecursive = */ false));
   }

   FieldScopeLogic allowingFieldDescriptors(Iterable<FieldDescriptor> fieldDescriptors) {
     if (isEmpty(fieldDescriptors)) {
       return this;
     }
     return or(this, new FieldDescriptorsLogic(fieldDescriptors, /* isRecursive = */ true));
   }

   FieldScopeLogic allowingFieldDescriptorsNonRecursive(Iterable<FieldDescriptor> fieldDescriptors) {
     if (isEmpty(fieldDescriptors)) {
       return this;
     }
     return or(this, new FieldDescriptorsLogic(fieldDescriptors, /* isRecursive = */ false));
   }

   //////////////////////////////////////////////////////////////////////////////////////////////////
   // CONCRETE SUBTYPES
   //////////////////////////////////////////////////////////////////////////////////////////////////

   /** Returns whether this is equivalent to {@code FieldScopeLogic.all()}. */
   boolean isAll() {
     return false;
   }

   private static final FieldScopeLogic ALL =
       new FieldScopeLogic() {
         @Override
         public String toString() {
           return "FieldScopes.all()";
         }

         @Override
         final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
           return FieldScopeResult.INCLUDED_RECURSIVELY;
         }

         @Override
         final boolean isAll() {
           return true;
         }
       };

   private static final FieldScopeLogic NONE =
       new FieldScopeLogic() {
         @Override
         public String toString() {
           return "FieldScopes.none()";
         }

         @Override
         final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
           return FieldScopeResult.EXCLUDED_RECURSIVELY;
         }
       };

   static FieldScopeLogic all() {
     return ALL;
   }

   static FieldScopeLogic none() {
     return NONE;
   }

   private static class PartialScopeLogic extends FieldScopeLogic {
     private static final PartialScopeLogic EMPTY = new PartialScopeLogic(FieldNumberTree.empty());

     private final FieldNumberTree fieldNumberTree;

     PartialScopeLogic(FieldNumberTree fieldNumberTree) {
       this.fieldNumberTree = fieldNumberTree;
     }

     @Override
     public String toString() {
       return String.format("PartialScopeLogic(%s)", fieldNumberTree);
     }

     @Override
     final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
       return fieldNumberTree.hasChild(subScopeId)
           ? FieldScopeResult.INCLUDED_NONRECURSIVELY
           : FieldScopeResult.EXCLUDED_RECURSIVELY;
     }

     @Override
     final FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
       return newPartialScopeLogic(fieldNumberTree.child(subScopeId));
     }

     private static PartialScopeLogic newPartialScopeLogic(FieldNumberTree fieldNumberTree) {
       return fieldNumberTree.isEmpty() ? EMPTY : new PartialScopeLogic(fieldNumberTree);
     }
   }

   private static final class RootPartialScopeLogic extends PartialScopeLogic {
     private final String repr;
     private final Descriptor expectedDescriptor;

     RootPartialScopeLogic(FieldNumberTree fieldNumberTree, String repr, Descriptor descriptor) {
       super(fieldNumberTree);
       this.repr = repr;
       this.expectedDescriptor = descriptor;
     }

     @Override
     public void validate(
         Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
       Verify.verify(
           fieldDescriptorValidator == FieldDescriptorValidator.ALLOW_ALL,
           "PartialScopeLogic doesn't support custom field validators.");

       checkArgument(
           expectedDescriptor.equals(rootDescriptor),
           "Message given to FieldScopes.fromSetFields() does not have the same descriptor as the "
               + "message being tested. Expected %s, got %s.",
           expectedDescriptor.getFullName(),
           rootDescriptor.getFullName());
     }

     @Override
     public String toString() {
       return String.format("FieldScopes.fromSetFields(%s)", repr);
     }
   }

   static FieldScopeLogic partialScope(
       Message message, TypeRegistry typeRegistry, ExtensionRegistry extensionRegistry) {
     return new RootPartialScopeLogic(
         FieldNumberTree.fromMessage(message, typeRegistry, extensionRegistry),
         message.toString(),
         message.getDescriptorForType());
   }

   static FieldScopeLogic partialScope(
       Iterable<? extends Message> messages,
       Descriptor descriptor,
       TypeRegistry typeRegistry,
       ExtensionRegistry extensionRegistry) {
     return new RootPartialScopeLogic(
         FieldNumberTree.fromMessages(messages, typeRegistry, extensionRegistry),
         Joiner.on(", ").useForNull("null").join(messages),
         descriptor);
   }

   // TODO(user): Performance: Optimize FieldNumbersLogic and FieldDescriptorsLogic for
   // adding / ignoring field numbers and descriptors, respectively, to eliminate high recursion
   // costs for long chains of allows/ignores.

   // Common functionality for FieldNumbersLogic and FieldDescriptorsLogic.
   private abstract static class FieldMatcherLogicBase extends FieldScopeLogic {

     private final boolean isRecursive;

     protected FieldMatcherLogicBase(boolean isRecursive) {
       this.isRecursive = isRecursive;
     }

     /**
      * Determines whether the FieldDescriptor is equal to one of the explicitly defined components
      * of this FieldScopeLogic.
      *
      * @param descriptor Descriptor of the message being tested.
      * @param fieldDescriptor FieldDescriptor being inspected for a direct match to the scope's
      *     definition.
      */
     abstract boolean matchesFieldDescriptor(Descriptor descriptor, FieldDescriptor fieldDescriptor);

     @Override
     final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
       FieldDescriptor fieldDescriptor = null;
       switch (subScopeId.kind()) {
         case FIELD_DESCRIPTOR:
           fieldDescriptor = subScopeId.fieldDescriptor();
           break;
         case UNPACKED_ANY_VALUE_TYPE:
           fieldDescriptor = AnyUtils.valueFieldDescriptor();
           break;
         case UNKNOWN_FIELD_DESCRIPTOR:
           return FieldScopeResult.EXCLUDED_RECURSIVELY;
       }

       if (matchesFieldDescriptor(rootDescriptor, fieldDescriptor)) {
         return FieldScopeResult.of(/* included = */ true, isRecursive);
       }

       // We return 'EXCLUDED_NONRECURSIVELY' for both field descriptor scopes and field number
       // scopes. In the former case, the field descriptors are arbitrary, so it's always possible we
       // find a hit on a sub-message somewhere.  In the latter case, the message definition may be
       // cyclic, so we need to return 'EXCLUDED_NONRECURSIVELY' even if the top level field number
       // doesn't match.
       return FieldScopeResult.EXCLUDED_NONRECURSIVELY;
     }

     @Override
     final FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
       return this;
     }

     @Override
     public void validate(
         Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
       if (isRecursive) {
         Verify.verify(
             fieldDescriptorValidator == FieldDescriptorValidator.ALLOW_ALL,
             "Field descriptor validators are not supported "
                 + "for non-recursive field matcher logics.");
       }
     }
   }

   // Matches any specific fields which fall under a sub-message field (or root) matching the root
   // message type and one of the specified field numbers.
   private static final class FieldNumbersLogic extends FieldMatcherLogicBase {
     private final ImmutableSet<Integer> fieldNumbers;

     FieldNumbersLogic(Iterable<Integer> fieldNumbers, boolean isRecursive) {
       super(isRecursive);
       this.fieldNumbers = ImmutableSet.copyOf(fieldNumbers);
     }

     @Override
     public void validate(
         Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
       super.validate(rootDescriptor, fieldDescriptorValidator);
       for (int fieldNumber : fieldNumbers) {
         FieldDescriptor fieldDescriptor = rootDescriptor.findFieldByNumber(fieldNumber);
         checkArgument(
             fieldDescriptor != null,
             "Message type %s has no field with number %s.",
             rootDescriptor.getFullName(),
             fieldNumber);
         fieldDescriptorValidator.validate(fieldDescriptor);
       }
     }

     @Override
     boolean matchesFieldDescriptor(Descriptor descriptor, FieldDescriptor fieldDescriptor) {
       return fieldDescriptor.getContainingType() == descriptor
           && fieldNumbers.contains(fieldDescriptor.getNumber());
     }

     @Override
     public String toString() {
       return String.format("FieldScopes.allowingFields(%s)", join(fieldNumbers));
     }
   }

   // Matches any specific fields which fall under one of the specified FieldDescriptors.
   private static final class FieldDescriptorsLogic extends FieldMatcherLogicBase {
     private final ImmutableSet<FieldDescriptor> fieldDescriptors;

     FieldDescriptorsLogic(Iterable<FieldDescriptor> fieldDescriptors, boolean isRecursive) {
       super(isRecursive);
       this.fieldDescriptors = ImmutableSet.copyOf(fieldDescriptors);
     }

     @Override
     boolean matchesFieldDescriptor(Descriptor descriptor, FieldDescriptor fieldDescriptor) {
       return fieldDescriptors.contains(fieldDescriptor);
     }

     @Override
     public void validate(
         Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
       super.validate(rootDescriptor, fieldDescriptorValidator);
       for (FieldDescriptor fieldDescriptor : fieldDescriptors) {
         fieldDescriptorValidator.validate(fieldDescriptor);
       }
     }

     @Override
     public String toString() {
       return String.format("FieldScopes.allowingFieldDescriptors(%s)", join(fieldDescriptors));
     }
   }

   //////////////////////////////////////////////////////////////////////////////////////////////////
   // COMPOUND SUBTYPES
   //////////////////////////////////////////////////////////////////////////////////////////////////

   private abstract static class CompoundFieldScopeLogic<T extends CompoundFieldScopeLogic<T>>
       extends FieldScopeLogic {
     final ImmutableList<FieldScopeLogic> elements;

     CompoundFieldScopeLogic(FieldScopeLogic singleElem) {
       this.elements = ImmutableList.of(singleElem);
     }

     CompoundFieldScopeLogic(FieldScopeLogic firstElem, FieldScopeLogic secondElem) {
       this.elements = ImmutableList.of(firstElem, secondElem);
     }

     @Override
     public final void validate(
         Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
       for (FieldScopeLogic elem : elements) {
         elem.validate(rootDescriptor, fieldDescriptorValidator);
       }
     }

     /** Helper to produce a new {@code CompoundFieldScopeLogic} of the same type as the subclass. */
     abstract T newLogicOfSameType(List<FieldScopeLogic> newElements);

     @Override
     final FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
       ImmutableList.Builder<FieldScopeLogic> builder =
           ImmutableList.builderWithExpectedSize(elements.size());
       for (FieldScopeLogic elem : elements) {
         builder.add(elem.subScope(rootDescriptor, subScopeId));
       }
       return newLogicOfSameType(builder.build());
     }
   }

   private static final class IntersectionFieldScopeLogic
       extends CompoundFieldScopeLogic<IntersectionFieldScopeLogic> {
     IntersectionFieldScopeLogic(FieldScopeLogic subject1, FieldScopeLogic subject2) {
       super(subject1, subject2);
     }

     @Override
     IntersectionFieldScopeLogic newLogicOfSameType(List<FieldScopeLogic> newElements) {
       checkArgument(newElements.size() == 2, "Expected 2 elements: %s", newElements);
       return new IntersectionFieldScopeLogic(newElements.get(0), newElements.get(1));
     }

     @Override
     FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
       // The intersection of two scopes is ignorable if either scope is itself ignorable.
       return intersection(
           elements.get(0).policyFor(rootDescriptor, subScopeId),
           elements.get(1).policyFor(rootDescriptor, subScopeId));
     }

     private static FieldScopeResult intersection(
         FieldScopeResult result1, FieldScopeResult result2) {
       if (result1 == FieldScopeResult.EXCLUDED_RECURSIVELY
           || result2 == FieldScopeResult.EXCLUDED_RECURSIVELY) {
         // If either argument is excluded recursively, the result is too.
         return FieldScopeResult.EXCLUDED_RECURSIVELY;
       } else if (!result1.included() || !result2.included()) {
         // Otherwise, we exclude non-recursively if either result is an exclusion.
         return FieldScopeResult.EXCLUDED_NONRECURSIVELY;
       } else if (result1.recursive() && result2.recursive()) {
         // We include recursively if both arguments are recursive.
         return FieldScopeResult.INCLUDED_RECURSIVELY;
       } else {
         // Otherwise, we include non-recursively.
         return FieldScopeResult.INCLUDED_NONRECURSIVELY;
       }
     }

     @Override
     public String toString() {
       return String.format("(%s && %s)", elements.get(0), elements.get(1));
     }
   }

   private static final class UnionFieldScopeLogic
       extends CompoundFieldScopeLogic<UnionFieldScopeLogic> {
     UnionFieldScopeLogic(FieldScopeLogic subject1, FieldScopeLogic subject2) {
       super(subject1, subject2);
     }

     @Override
     UnionFieldScopeLogic newLogicOfSameType(List<FieldScopeLogic> newElements) {
       checkArgument(newElements.size() == 2, "Expected 2 elements: %s", newElements);
       return new UnionFieldScopeLogic(newElements.get(0), newElements.get(1));
     }

     @Override
     FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
       // The union of two scopes is ignorable only if both scopes are themselves ignorable.
       return union(
           elements.get(0).policyFor(rootDescriptor, subScopeId),
           elements.get(1).policyFor(rootDescriptor, subScopeId));
     }

     private static FieldScopeResult union(FieldScopeResult result1, FieldScopeResult result2) {
       if (result1 == FieldScopeResult.INCLUDED_RECURSIVELY
           || result2 == FieldScopeResult.INCLUDED_RECURSIVELY) {
         // If either argument is included recursively, the result is too.
         return FieldScopeResult.INCLUDED_RECURSIVELY;
       } else if (result1.included() || result2.included()) {
         // Otherwise, if either is included, we include non-recursively.
         return FieldScopeResult.INCLUDED_NONRECURSIVELY;
       } else if (result1.recursive() && result2.recursive()) {
         // If both arguments are recursive, we exclude recursively.
         return FieldScopeResult.EXCLUDED_RECURSIVELY;
       } else {
         // Otherwise, we exclude exclude non-recursively.
         return FieldScopeResult.EXCLUDED_NONRECURSIVELY;
       }
     }

     @Override
     public String toString() {
       return String.format("(%s || %s)", elements.get(0), elements.get(1));
     }
   }

   private static final class NegationFieldScopeLogic
       extends CompoundFieldScopeLogic<NegationFieldScopeLogic> {
     NegationFieldScopeLogic(FieldScopeLogic subject) {
       super(subject);
     }

     @Override
     NegationFieldScopeLogic newLogicOfSameType(List<FieldScopeLogic> newElements) {
       checkArgument(newElements.size() == 1, "Expected 1 element: %s", newElements);
       return new NegationFieldScopeLogic(newElements.get(0));
     }

     @Override
     FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
       FieldScopeResult result = elements.get(0).policyFor(rootDescriptor, subScopeId);
       return FieldScopeResult.of(!result.included(), result.recursive());
     }

     @Override
     public String toString() {
       return String.format("!(%s)", elements.get(0));
     }
   }

   static FieldScopeLogic and(FieldScopeLogic fieldScopeLogic1, FieldScopeLogic fieldScopeLogic2) {
     return new IntersectionFieldScopeLogic(fieldScopeLogic1, fieldScopeLogic2);
   }

   static FieldScopeLogic or(FieldScopeLogic fieldScopeLogic1, FieldScopeLogic fieldScopeLogic2) {
     return new UnionFieldScopeLogic(fieldScopeLogic1, fieldScopeLogic2);
   }

   static FieldScopeLogic not(FieldScopeLogic fieldScopeLogic) {
     return new NegationFieldScopeLogic(fieldScopeLogic);
   }
 }
	/*
	* Copyright (c) 2016 Google, Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package com.google.common.truth.extensions.proto;

	import static com.google.common.base.Preconditions.checkArgument;
	import static com.google.common.base.Preconditions.checkNotNull;
	import static com.google.common.truth.extensions.proto.FieldScopeUtil.join;

	import com.google.common.base.Joiner;
	import com.google.common.base.Optional;
	import com.google.common.base.Verify;
	import com.google.common.collect.ImmutableList;
	import com.google.common.collect.ImmutableSet;
	import com.google.errorprone.annotations.ForOverride;
	import com.google.protobuf.Descriptors.Descriptor;
	import com.google.protobuf.Descriptors.FieldDescriptor;
	import com.google.protobuf.ExtensionRegistry;
	import com.google.protobuf.Message;
	import com.google.protobuf.TypeRegistry;
	import java.util.List;

	/**
	* Implementations of all variations of {@link FieldScope} logic.
	*
	* <p>{@code FieldScopeLogic} is the abstract base class which provides common functionality to all
	* sub-types. There are two classes of sub-types:
	*
	* <ul>
	* <li>Concrete subtypes, which implements specific rules and perform no delegation.
	* <li>Compound subtypes, which combine one or more {@code FieldScopeLogic}s with specific
	* operations.
	* </ul>
	*/
	abstract class FieldScopeLogic implements FieldScopeLogicContainer<FieldScopeLogic> {

	/**
	* Returns whether the given field is included in this FieldScopeLogic, along with whether it's
	* included recursively or not.
	*/
	abstract FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId);

	/** Returns whether the given field is included in this FieldScopeLogic. */
	final boolean contains(Descriptor rootDescriptor, SubScopeId subScopeId) {
	return policyFor(rootDescriptor, subScopeId).included();
	}

	/**
	* Returns a {@code FieldScopeLogic} to handle the message pointed to by this descriptor.
	*
	* <p>Subclasses which can return non-recursive {@link FieldScopeResult}s must override {@link
	* #subScopeImpl} to implement those cases.
	*/
	@Override
	public final FieldScopeLogic subScope(Descriptor rootDescriptor, SubScopeId subScopeId) {
	FieldScopeResult result = policyFor(rootDescriptor, subScopeId);
	if (result.recursive()) {
	return result.included() ? all() : none();
	} else {
	return subScopeImpl(rootDescriptor, subScopeId);
	}
	}

	/**
	* Returns {@link #subScope} for {@code NONRECURSIVE} results.
	*
	* <p>Throws an {@link UnsupportedOperationException} by default. Subclasses which can return
	* {@code NONRECURSIVE} results must override this method.
	*/
	@ForOverride
	FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
	throw new UnsupportedOperationException("subScopeImpl not implemented for " + getClass());
	}

	/**
	* Returns an accurate description for debugging purposes.
	*
	* <p>Compare to {@link FieldScope#usingCorrespondenceString(Optional)}, which returns a beautiful
	* error message that makes as much sense to the user as possible.
	*
	* <p>Abstract so subclasses must implement.
	*/
	@Override
	public abstract String toString();

	@Override
	public void validate(
	Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {}

	private static boolean isEmpty(Iterable<?> container) {
	boolean isEmpty = true;
	for (Object element : container) {
	checkNotNull(element);
	isEmpty = false;
	}

	return isEmpty;
	}

	// TODO(user): Rename these 'ignoring' and 'allowing' methods to 'plus' and 'minus', or
	// something else that doesn't tightly couple FieldScopeLogic to the 'ignore' concept.
	FieldScopeLogic ignoringFields(Iterable<Integer> fieldNumbers) {
	if (isEmpty(fieldNumbers)) {
	return this;
	}
	return and(
	this,
	new NegationFieldScopeLogic(new FieldNumbersLogic(fieldNumbers, /* isRecursive = */ true)));
	}

	FieldScopeLogic ignoringFieldDescriptors(Iterable<FieldDescriptor> fieldDescriptors) {
	if (isEmpty(fieldDescriptors)) {
	return this;
	}
	return and(
	this,
	new NegationFieldScopeLogic(
	new FieldDescriptorsLogic(fieldDescriptors, /* isRecursive = */ true)));
	}

	FieldScopeLogic allowingFields(Iterable<Integer> fieldNumbers) {
	if (isEmpty(fieldNumbers)) {
	return this;
	}
	return or(this, new FieldNumbersLogic(fieldNumbers, /* isRecursive = */ true));
	}

	FieldScopeLogic allowingFieldsNonRecursive(Iterable<Integer> fieldNumbers) {
	if (isEmpty(fieldNumbers)) {
	return this;
	}
	return or(this, new FieldNumbersLogic(fieldNumbers, /* isRecursive = */ false));
	}

	FieldScopeLogic allowingFieldDescriptors(Iterable<FieldDescriptor> fieldDescriptors) {
	if (isEmpty(fieldDescriptors)) {
	return this;
	}
	return or(this, new FieldDescriptorsLogic(fieldDescriptors, /* isRecursive = */ true));
	}

	FieldScopeLogic allowingFieldDescriptorsNonRecursive(Iterable<FieldDescriptor> fieldDescriptors) {
	if (isEmpty(fieldDescriptors)) {
	return this;
	}
	return or(this, new FieldDescriptorsLogic(fieldDescriptors, /* isRecursive = */ false));
	}

	//////////////////////////////////////////////////////////////////////////////////////////////////
	// CONCRETE SUBTYPES
	//////////////////////////////////////////////////////////////////////////////////////////////////

	/** Returns whether this is equivalent to {@code FieldScopeLogic.all()}. */
	boolean isAll() {
	return false;
	}

	private static final FieldScopeLogic ALL =
	new FieldScopeLogic() {
	@Override
	public String toString() {
	return "FieldScopes.all()";
	}

	@Override
	final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	return FieldScopeResult.INCLUDED_RECURSIVELY;
	}

	@Override
	final boolean isAll() {
	return true;
	}
	};

	private static final FieldScopeLogic NONE =
	new FieldScopeLogic() {
	@Override
	public String toString() {
	return "FieldScopes.none()";
	}

	@Override
	final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	return FieldScopeResult.EXCLUDED_RECURSIVELY;
	}
	};

	static FieldScopeLogic all() {
	return ALL;
	}

	static FieldScopeLogic none() {
	return NONE;
	}

	private static class PartialScopeLogic extends FieldScopeLogic {
	private static final PartialScopeLogic EMPTY = new PartialScopeLogic(FieldNumberTree.empty());

	private final FieldNumberTree fieldNumberTree;

	PartialScopeLogic(FieldNumberTree fieldNumberTree) {
	this.fieldNumberTree = fieldNumberTree;
	}

	@Override
	public String toString() {
	return String.format("PartialScopeLogic(%s)", fieldNumberTree);
	}

	@Override
	final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	return fieldNumberTree.hasChild(subScopeId)
	? FieldScopeResult.INCLUDED_NONRECURSIVELY
	: FieldScopeResult.EXCLUDED_RECURSIVELY;
	}

	@Override
	final FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
	return newPartialScopeLogic(fieldNumberTree.child(subScopeId));
	}

	private static PartialScopeLogic newPartialScopeLogic(FieldNumberTree fieldNumberTree) {
	return fieldNumberTree.isEmpty() ? EMPTY : new PartialScopeLogic(fieldNumberTree);
	}
	}

	private static final class RootPartialScopeLogic extends PartialScopeLogic {
	private final String repr;
	private final Descriptor expectedDescriptor;

	RootPartialScopeLogic(FieldNumberTree fieldNumberTree, String repr, Descriptor descriptor) {
	super(fieldNumberTree);
	this.repr = repr;
	this.expectedDescriptor = descriptor;
	}

	@Override
	public void validate(
	Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
	Verify.verify(
	fieldDescriptorValidator == FieldDescriptorValidator.ALLOW_ALL,
	"PartialScopeLogic doesn't support custom field validators.");

	checkArgument(
	expectedDescriptor.equals(rootDescriptor),
	"Message given to FieldScopes.fromSetFields() does not have the same descriptor as the "
	+ "message being tested. Expected %s, got %s.",
	expectedDescriptor.getFullName(),
	rootDescriptor.getFullName());
	}

	@Override
	public String toString() {
	return String.format("FieldScopes.fromSetFields(%s)", repr);
	}
	}

	static FieldScopeLogic partialScope(
	Message message, TypeRegistry typeRegistry, ExtensionRegistry extensionRegistry) {
	return new RootPartialScopeLogic(
	FieldNumberTree.fromMessage(message, typeRegistry, extensionRegistry),
	message.toString(),
	message.getDescriptorForType());
	}

	static FieldScopeLogic partialScope(
	Iterable<? extends Message> messages,
	Descriptor descriptor,
	TypeRegistry typeRegistry,
	ExtensionRegistry extensionRegistry) {
	return new RootPartialScopeLogic(
	FieldNumberTree.fromMessages(messages, typeRegistry, extensionRegistry),
	Joiner.on(", ").useForNull("null").join(messages),
	descriptor);
	}

	// TODO(user): Performance: Optimize FieldNumbersLogic and FieldDescriptorsLogic for
	// adding / ignoring field numbers and descriptors, respectively, to eliminate high recursion
	// costs for long chains of allows/ignores.

	// Common functionality for FieldNumbersLogic and FieldDescriptorsLogic.
	private abstract static class FieldMatcherLogicBase extends FieldScopeLogic {

	private final boolean isRecursive;

	protected FieldMatcherLogicBase(boolean isRecursive) {
	this.isRecursive = isRecursive;
	}

	/**
	* Determines whether the FieldDescriptor is equal to one of the explicitly defined components
	* of this FieldScopeLogic.
	*
	* @param descriptor Descriptor of the message being tested.
	* @param fieldDescriptor FieldDescriptor being inspected for a direct match to the scope's
	* definition.
	*/
	abstract boolean matchesFieldDescriptor(Descriptor descriptor, FieldDescriptor fieldDescriptor);

	@Override
	final FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	FieldDescriptor fieldDescriptor = null;
	switch (subScopeId.kind()) {
	case FIELD_DESCRIPTOR:
	fieldDescriptor = subScopeId.fieldDescriptor();
	break;
	case UNPACKED_ANY_VALUE_TYPE:
	fieldDescriptor = AnyUtils.valueFieldDescriptor();
	break;
	case UNKNOWN_FIELD_DESCRIPTOR:
	return FieldScopeResult.EXCLUDED_RECURSIVELY;
	}

	if (matchesFieldDescriptor(rootDescriptor, fieldDescriptor)) {
	return FieldScopeResult.of(/* included = */ true, isRecursive);
	}

	// We return 'EXCLUDED_NONRECURSIVELY' for both field descriptor scopes and field number
	// scopes. In the former case, the field descriptors are arbitrary, so it's always possible we
	// find a hit on a sub-message somewhere. In the latter case, the message definition may be
	// cyclic, so we need to return 'EXCLUDED_NONRECURSIVELY' even if the top level field number
	// doesn't match.
	return FieldScopeResult.EXCLUDED_NONRECURSIVELY;
	}

	@Override
	final FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
	return this;
	}

	@Override
	public void validate(
	Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
	if (isRecursive) {
	Verify.verify(
	fieldDescriptorValidator == FieldDescriptorValidator.ALLOW_ALL,
	"Field descriptor validators are not supported "
	+ "for non-recursive field matcher logics.");
	}
	}
	}

	// Matches any specific fields which fall under a sub-message field (or root) matching the root
	// message type and one of the specified field numbers.
	private static final class FieldNumbersLogic extends FieldMatcherLogicBase {
	private final ImmutableSet<Integer> fieldNumbers;

	FieldNumbersLogic(Iterable<Integer> fieldNumbers, boolean isRecursive) {
	super(isRecursive);
	this.fieldNumbers = ImmutableSet.copyOf(fieldNumbers);
	}

	@Override
	public void validate(
	Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
	super.validate(rootDescriptor, fieldDescriptorValidator);
	for (int fieldNumber : fieldNumbers) {
	FieldDescriptor fieldDescriptor = rootDescriptor.findFieldByNumber(fieldNumber);
	checkArgument(
	fieldDescriptor != null,
	"Message type %s has no field with number %s.",
	rootDescriptor.getFullName(),
	fieldNumber);
	fieldDescriptorValidator.validate(fieldDescriptor);
	}
	}

	@Override
	boolean matchesFieldDescriptor(Descriptor descriptor, FieldDescriptor fieldDescriptor) {
	return fieldDescriptor.getContainingType() == descriptor
	&& fieldNumbers.contains(fieldDescriptor.getNumber());
	}

	@Override
	public String toString() {
	return String.format("FieldScopes.allowingFields(%s)", join(fieldNumbers));
	}
	}

	// Matches any specific fields which fall under one of the specified FieldDescriptors.
	private static final class FieldDescriptorsLogic extends FieldMatcherLogicBase {
	private final ImmutableSet<FieldDescriptor> fieldDescriptors;

	FieldDescriptorsLogic(Iterable<FieldDescriptor> fieldDescriptors, boolean isRecursive) {
	super(isRecursive);
	this.fieldDescriptors = ImmutableSet.copyOf(fieldDescriptors);
	}

	@Override
	boolean matchesFieldDescriptor(Descriptor descriptor, FieldDescriptor fieldDescriptor) {
	return fieldDescriptors.contains(fieldDescriptor);
	}

	@Override
	public void validate(
	Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
	super.validate(rootDescriptor, fieldDescriptorValidator);
	for (FieldDescriptor fieldDescriptor : fieldDescriptors) {
	fieldDescriptorValidator.validate(fieldDescriptor);
	}
	}

	@Override
	public String toString() {
	return String.format("FieldScopes.allowingFieldDescriptors(%s)", join(fieldDescriptors));
	}
	}

	//////////////////////////////////////////////////////////////////////////////////////////////////
	// COMPOUND SUBTYPES
	//////////////////////////////////////////////////////////////////////////////////////////////////

	private abstract static class CompoundFieldScopeLogic<T extends CompoundFieldScopeLogic<T>>
	extends FieldScopeLogic {
	final ImmutableList<FieldScopeLogic> elements;

	CompoundFieldScopeLogic(FieldScopeLogic singleElem) {
	this.elements = ImmutableList.of(singleElem);
	}

	CompoundFieldScopeLogic(FieldScopeLogic firstElem, FieldScopeLogic secondElem) {
	this.elements = ImmutableList.of(firstElem, secondElem);
	}

	@Override
	public final void validate(
	Descriptor rootDescriptor, FieldDescriptorValidator fieldDescriptorValidator) {
	for (FieldScopeLogic elem : elements) {
	elem.validate(rootDescriptor, fieldDescriptorValidator);
	}
	}

	/** Helper to produce a new {@code CompoundFieldScopeLogic} of the same type as the subclass. */
	abstract T newLogicOfSameType(List<FieldScopeLogic> newElements);

	@Override
	final FieldScopeLogic subScopeImpl(Descriptor rootDescriptor, SubScopeId subScopeId) {
	ImmutableList.Builder<FieldScopeLogic> builder =
	ImmutableList.builderWithExpectedSize(elements.size());
	for (FieldScopeLogic elem : elements) {
	builder.add(elem.subScope(rootDescriptor, subScopeId));
	}
	return newLogicOfSameType(builder.build());
	}
	}

	private static final class IntersectionFieldScopeLogic
	extends CompoundFieldScopeLogic<IntersectionFieldScopeLogic> {
	IntersectionFieldScopeLogic(FieldScopeLogic subject1, FieldScopeLogic subject2) {
	super(subject1, subject2);
	}

	@Override
	IntersectionFieldScopeLogic newLogicOfSameType(List<FieldScopeLogic> newElements) {
	checkArgument(newElements.size() == 2, "Expected 2 elements: %s", newElements);
	return new IntersectionFieldScopeLogic(newElements.get(0), newElements.get(1));
	}

	@Override
	FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	// The intersection of two scopes is ignorable if either scope is itself ignorable.
	return intersection(
	elements.get(0).policyFor(rootDescriptor, subScopeId),
	elements.get(1).policyFor(rootDescriptor, subScopeId));
	}

	private static FieldScopeResult intersection(
	FieldScopeResult result1, FieldScopeResult result2) {
	if (result1 == FieldScopeResult.EXCLUDED_RECURSIVELY
	\|\| result2 == FieldScopeResult.EXCLUDED_RECURSIVELY) {
	// If either argument is excluded recursively, the result is too.
	return FieldScopeResult.EXCLUDED_RECURSIVELY;
	} else if (!result1.included() \|\| !result2.included()) {
	// Otherwise, we exclude non-recursively if either result is an exclusion.
	return FieldScopeResult.EXCLUDED_NONRECURSIVELY;
	} else if (result1.recursive() && result2.recursive()) {
	// We include recursively if both arguments are recursive.
	return FieldScopeResult.INCLUDED_RECURSIVELY;
	} else {
	// Otherwise, we include non-recursively.
	return FieldScopeResult.INCLUDED_NONRECURSIVELY;
	}
	}

	@Override
	public String toString() {
	return String.format("(%s && %s)", elements.get(0), elements.get(1));
	}
	}

	private static final class UnionFieldScopeLogic
	extends CompoundFieldScopeLogic<UnionFieldScopeLogic> {
	UnionFieldScopeLogic(FieldScopeLogic subject1, FieldScopeLogic subject2) {
	super(subject1, subject2);
	}

	@Override
	UnionFieldScopeLogic newLogicOfSameType(List<FieldScopeLogic> newElements) {
	checkArgument(newElements.size() == 2, "Expected 2 elements: %s", newElements);
	return new UnionFieldScopeLogic(newElements.get(0), newElements.get(1));
	}

	@Override
	FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	// The union of two scopes is ignorable only if both scopes are themselves ignorable.
	return union(
	elements.get(0).policyFor(rootDescriptor, subScopeId),
	elements.get(1).policyFor(rootDescriptor, subScopeId));
	}

	private static FieldScopeResult union(FieldScopeResult result1, FieldScopeResult result2) {
	if (result1 == FieldScopeResult.INCLUDED_RECURSIVELY
	\|\| result2 == FieldScopeResult.INCLUDED_RECURSIVELY) {
	// If either argument is included recursively, the result is too.
	return FieldScopeResult.INCLUDED_RECURSIVELY;
	} else if (result1.included() \|\| result2.included()) {
	// Otherwise, if either is included, we include non-recursively.
	return FieldScopeResult.INCLUDED_NONRECURSIVELY;
	} else if (result1.recursive() && result2.recursive()) {
	// If both arguments are recursive, we exclude recursively.
	return FieldScopeResult.EXCLUDED_RECURSIVELY;
	} else {
	// Otherwise, we exclude exclude non-recursively.
	return FieldScopeResult.EXCLUDED_NONRECURSIVELY;
	}
	}

	@Override
	public String toString() {
	return String.format("(%s \|\| %s)", elements.get(0), elements.get(1));
	}
	}

	private static final class NegationFieldScopeLogic
	extends CompoundFieldScopeLogic<NegationFieldScopeLogic> {
	NegationFieldScopeLogic(FieldScopeLogic subject) {
	super(subject);
	}

	@Override
	NegationFieldScopeLogic newLogicOfSameType(List<FieldScopeLogic> newElements) {
	checkArgument(newElements.size() == 1, "Expected 1 element: %s", newElements);
	return new NegationFieldScopeLogic(newElements.get(0));
	}

	@Override
	FieldScopeResult policyFor(Descriptor rootDescriptor, SubScopeId subScopeId) {
	FieldScopeResult result = elements.get(0).policyFor(rootDescriptor, subScopeId);
	return FieldScopeResult.of(!result.included(), result.recursive());
	}

	@Override
	public String toString() {
	return String.format("!(%s)", elements.get(0));
	}
	}

	static FieldScopeLogic and(FieldScopeLogic fieldScopeLogic1, FieldScopeLogic fieldScopeLogic2) {
	return new IntersectionFieldScopeLogic(fieldScopeLogic1, fieldScopeLogic2);
	}

	static FieldScopeLogic or(FieldScopeLogic fieldScopeLogic1, FieldScopeLogic fieldScopeLogic2) {
	return new UnionFieldScopeLogic(fieldScopeLogic1, fieldScopeLogic2);
	}

	static FieldScopeLogic not(FieldScopeLogic fieldScopeLogic) {
	return new NegationFieldScopeLogic(fieldScopeLogic);
	}
	}