content: /*
   * Copyright 2018 The Android Open Source Project
   *
   * 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 android.view.inspector;
  
  import android.annotation.NonNull;
  
  /**
   * An interface for companion objects used to inspect views.
   *
   * Inspection companions only need to handle the properties and node name of the specific class
   * they are defined for, not anything from a parent class. At runtime, the inspector instantiates
   * one instance of each inspection companion, and handles visiting them in the correct inheritance
   * order for each type it inspects.
   *
   * Properties are read from the top of the type tree to the bottom, so that classes that override
   * a property in their parent class can overwrite it in the reader. In general, properties will
   * cleanly inherit through their getters, and the inspector runtime will read the properties of a
   * parent class via the parent's inspection companion, and the child companion will only read
   * properties added or changed since the parent was defined.
   *
   * @param <T> The type of inspectable this is the companion to
   */
  public interface InspectionCompanion<T> {
      /**
       * Map the string names of the properties this companion knows about to integer IDs.
       *
       * Each companion is responsible for storing the integer IDs of all its properties. This is the
       * only method that is allowed to modify the stored IDs.
       *
       * Calling {@link #readProperties(T, PropertyReader)} before calling this results in
       * undefined behavior.
       *
       * @param propertyMapper A {@link PropertyMapper} maps string names to IDs.
       */
      void mapProperties(@NonNull PropertyMapper propertyMapper);
  
      /**
       * Read the values of an instance of this companion's type into a {@link PropertyReader}.
       *
       * This method needs to return the property IDs stored by
       * {@link #mapProperties(PropertyMapper)}. Implementations should track if their properties
       * have been mapped and throw a {@link UninitializedPropertyMapException} if this method is
       * called before {mapProperties}.
       *
       * @param inspectable A object of type {T} to read the properties of.
       * @param propertyReader An object which receives the property IDs and values.
       */
      void readProperties(@NonNull T inspectable, @NonNull PropertyReader propertyReader);
  
      /**
       * Thrown by {@link #readProperties(Object, PropertyReader)} if called before
       * {@link #mapProperties(PropertyMapper)}.
       */
      class UninitializedPropertyMapException extends RuntimeException {
          public UninitializedPropertyMapException() {
              super("Unable to read properties of an inspectable before mapping their IDs.");
          }
      }
  }
  