| /* |
| * 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.AnyRes; |
| import android.annotation.ColorInt; |
| import android.annotation.ColorLong; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.graphics.Color; |
| |
| /** |
| * An interface for reading the properties of an inspectable object. |
| * |
| * {@code PropertyReader} is defined as an interface that will be called by |
| * {@link InspectionCompanion#readProperties(Object, PropertyReader)}. This approach allows a |
| * client inspector to read the values of primitive properties without the overhead of |
| * instantiating a class to hold the property values for each inspection pass. If an inspectable |
| * remains unchanged between reading passes, it should be possible for a {@code PropertyReader} to |
| * avoid new allocations for subsequent reading passes. |
| * |
| * It has separate methods for all primitive types to avoid autoboxing overhead if a concrete |
| * implementation is able to work with primitives. Implementations should be prepared to accept |
| * {null} as the value of {@link PropertyReader#readObject(int, Object)}. |
| * |
| * @see InspectionCompanion#readProperties(Object, PropertyReader) |
| */ |
| public interface PropertyReader { |
| /** |
| * Read a primitive boolean property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code boolean} |
| */ |
| void readBoolean(int id, boolean value); |
| |
| /** |
| * Read a primitive byte property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code byte} |
| */ |
| void readByte(int id, byte value); |
| |
| /** |
| * Read a primitive character property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code char} |
| */ |
| void readChar(int id, char value); |
| |
| /** |
| * Read a read a primitive double property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code double} |
| */ |
| void readDouble(int id, double value); |
| |
| /** |
| * Read a primitive float property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code float} |
| */ |
| void readFloat(int id, float value); |
| |
| /** |
| * Read a primitive integer property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as an {@code int} |
| */ |
| void readInt(int id, int value); |
| |
| /** |
| * Read a primitive long property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code long} |
| */ |
| void readLong(int id, long value); |
| |
| /** |
| * Read a primitive short property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a {@code short} |
| */ |
| void readShort(int id, short value); |
| |
| /** |
| * Read any object as a property. |
| * |
| * If value is null, the property is marked as empty. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as an object |
| */ |
| void readObject(int id, @Nullable Object value); |
| |
| /** |
| * Read a color packed into a {@link ColorInt} as a property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a color |
| */ |
| void readColor(int id, @ColorInt int value); |
| |
| /** |
| * Read a color packed into a {@link ColorLong} as a property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a color |
| */ |
| void readColor(int id, @ColorLong long value); |
| |
| /** |
| * Read a {@link Color} object as a property. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a color |
| */ |
| void readColor(int id, @Nullable Color value); |
| |
| /** |
| * Read {@link android.view.Gravity} packed into an primitive {@code int}. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a gravity property |
| */ |
| void readGravity(int id, int value); |
| |
| /** |
| * Read an enumeration packed into a primitive {@code int}. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as an object |
| */ |
| void readIntEnum(int id, int value); |
| |
| /** |
| * Read a flag packed into a primitive {@code int}. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as an object |
| */ |
| void readIntFlag(int id, int value); |
| |
| /** |
| * Read an integer that contains a resource ID. |
| * |
| * @param id Identifier of the property from a {@link PropertyMapper} |
| * @param value Value of the property |
| * @throws PropertyTypeMismatchException If the property ID is not mapped as a resource ID. |
| */ |
| void readResourceId(int id, @AnyRes int value); |
| |
| /** |
| * Thrown if a client calls a typed read method for a property of a different type. |
| */ |
| class PropertyTypeMismatchException extends RuntimeException { |
| public PropertyTypeMismatchException( |
| int id, |
| @NonNull String expectedPropertyType, |
| @NonNull String actualPropertyType, |
| @Nullable String propertyName) { |
| super(formatMessage(id, expectedPropertyType, actualPropertyType, propertyName)); |
| } |
| |
| public PropertyTypeMismatchException( |
| int id, |
| @NonNull String expectedPropertyType, |
| @NonNull String actualPropertyType) { |
| super(formatMessage(id, expectedPropertyType, actualPropertyType, null)); |
| } |
| |
| private static @NonNull String formatMessage( |
| int id, |
| @NonNull String expectedPropertyType, |
| @NonNull String actualPropertyType, |
| @Nullable String propertyName) { |
| |
| if (propertyName == null) { |
| return String.format( |
| "Attempted to read property with ID 0x%08X as type %s, " |
| + "but the ID is of type %s.", |
| id, |
| expectedPropertyType, |
| actualPropertyType |
| ); |
| } else { |
| return String.format( |
| "Attempted to read property \"%s\" with ID 0x%08X as type %s, " |
| + "but the ID is of type %s.", |
| propertyName, |
| id, |
| expectedPropertyType, |
| actualPropertyType |
| ); |
| } |
| } |
| } |
| } |