core/java/android/view/inspector/PropertyMapper.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.AttrRes;
import android.annotation.NonNull;
import android.content.res.Resources;

import java.util.Set;
import java.util.function.IntFunction;

/**
 * An interface for mapping the string names of inspectable properties to integer identifiers.
 *
 * This interface is consumed by {@link InspectionCompanion#mapProperties(PropertyMapper)}.
 *
 * Mapping properties to IDs enables quick comparisons against shadow copies of inspectable
 * objects without performing a large number of string comparisons.
 *
 * Properties that derive their value from an XML attribute should provide the attribute resource
 * ID (e.g.: {@code R.attr.color}). For runtime or generated properties properties without
 * attribute IDs, supply {@link Resources#ID_NULL} for {@code attributeId}.
 *
 * @see InspectionCompanion#mapProperties(PropertyMapper)
 */
public interface PropertyMapper {
    /**
     * Map a string name to an integer ID for a primitive boolean property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapBoolean(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive byte property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapByte(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive char property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapChar(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive double property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapDouble(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive float property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapFloat(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive int property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapInt(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive long property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapLong(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a primitive short property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapShort(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for an object property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapObject(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a color property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     * @see android.graphics.Color
     */
    int mapColor(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a gravity property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     * @see android.view.Gravity
     */
    int mapGravity(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for an enumeration packed into an int property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @param mapping A mapping from int to String
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapIntEnum(
            @NonNull String name,
            @AttrRes int attributeId,
            @NonNull IntFunction<String> mapping);

    /**
     * Map a string name to an integer ID for an attribute that contains resource IDs.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapResourceId(@NonNull String name, @AttrRes int attributeId);

    /**
     * Map a string name to an integer ID for a flag set packed into an int property.
     *
     * @param name The name of the property
     * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL}
     * @param mapping A mapping from int to a set of strings
     * @return An integer ID for the property
     * @throws PropertyConflictException If the property name is already mapped as another type.
     */
    int mapIntFlag(
            @NonNull String name,
            @AttrRes int attributeId,
            @NonNull IntFunction<Set<String>> mapping);

    /**
     * Thrown from a map method if a property name is already mapped as different type.
     */
    class PropertyConflictException extends RuntimeException {
        public PropertyConflictException(
                @NonNull String name,
                @NonNull String newPropertyType,
                @NonNull String existingPropertyType) {
            super(String.format(
                    "Attempted to map property \"%s\" as type %s, but it is already mapped as %s.",
                    name,
                    newPropertyType,
                    existingPropertyType
            ));
        }
    }
}