core/java/android/view/inspector/InspectionHelper.java

/*
 * 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;
import android.annotation.Nullable;

/**
 * An interface for companion objects used to inspect views.
 *
 * Inspection helpers only need to handle the properties, name and traversal of the specific class
 * they are defined for, not anything from a parent class. At runtime, the inspector instantiates
 * one instance of each inspection helper, 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 helper, and the child helper will only read properties
 * added or changed since the parent was defined.
 *
 * Only one child traversal is considered for each class. If a descendant class defines a
 * different child traversal than its parent, only the bottom traversal is used. If a class does
 * not define its own child traversal, but one of its ancestors does, the bottom-most ancestor's
 * traversal will be used.
 *
 * @param <T> The type of inspectable this helper operates on
 * @hide
 */
public interface InspectionHelper<T> {
    /**
     * Map the string names of the properties this helper knows about to integer IDs.
     *
     * Each helper 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} or lambda which maps string names to IDs.
     */
    void mapProperties(@NonNull PropertyMapper propertyMapper);

    /**
     * Read the values of an instance of this helper'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 {@link 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);

    /**
     * Query if this inspectable type can potentially have child nodes.
     *
     * E.g.: any descendant of {@link android.view.ViewGroup} can have child nodes, but a leaf
     * view like {@link android.widget.ImageView} may not.
     *
     * The default implementation always returns false. If an implementing class overrides this, it
     * should also define {@link #traverseChildren(T, ChildTraverser)}.
     *
     * @return True if this inspectable type can potentially have child nodes, false otherwise.
     */
    default boolean hasChildTraversal() {
        return false;
    }

    /**
     * Traverse the child nodes of an instance of this helper's type into a {@link ChildTraverser}.
     *
     * This provides the ability to traverse over a variety of collection APIs (e.g.: arrays,
     * {@link Iterable}, or {@link java.util.Iterator}) in a uniform fashion. The traversal must be
     * in the order defined by this helper's type. If the getter returns null, the helper must
     * treat it as an empty collection.
     *
     * The default implementation throws a {@link NoChildTraversalException}. If
     * {@link #hasChildTraversal()} returns is overriden to return true, it is expected that the
     * implementing class will also override this method and provide a traversal.
     *
     * @param inspectable An object of type {@link T} to traverse the child nodes of.
     * @param childTraverser A {@link ChildTraverser} or lamba to receive the children in order.
     * @throws NoChildTraversalException If there is no defined child traversal
     */
    default void traverseChildren(
            @NonNull T inspectable,
            @SuppressWarnings("unused") @NonNull ChildTraverser childTraverser) {
        throw new NoChildTraversalException(inspectable.getClass());
    }

    /**
     * Get an optional name to display to developers for inspection nodes of this helper's type.
     *
     * The default implementation returns null, which will cause the runtime to use the class's
     * simple name as defined by {@link Class#getSimpleName()} as the node name.
     *
     * If the type of this helper is inflated from XML, this method should be overridden to return
     * the string used as the tag name for this type in XML.
     *
     * @return A string to use as the node name, or null to use the simple class name fallback.
     */
    @Nullable
    default String getNodeName() {
        return null;
    }

    /**
     * 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.");
        }
    }

    /**
     * Thrown by {@link #traverseChildren(Object, ChildTraverser)} if no child traversal exists.
     */
    class NoChildTraversalException extends RuntimeException {
        public NoChildTraversalException(Class cls) {
            super(String.format(
                    "Class %s does not have a defined child traversal. Cannot traverse children.",
                    cls.getCanonicalName()
            ));
        }
    }
}