Merge "Add Inspector annotations"

    ],

}

// A host library containing the inspector annotations for inspector-annotation-processor.

java_library_host {

    name: "inspector-annotation",

    srcs: [

        "core/java/android/view/inspector/InspectableChildren.java",

        "core/java/android/view/inspector/InspectableNodeName.java",

        "core/java/android/view/inspector/InspectableProperty.java",

    ],

}

// A host library including just UnsupportedAppUsage.java so that the annotation

// processor can also use this annotation.

java_library_host {

/*

 * 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 static java.lang.annotation.ElementType.METHOD;

import static java.lang.annotation.RetentionPolicy.SOURCE;

import java.lang.annotation.Retention;

import java.lang.annotation.Target;

/**

 * Marks a getter for an inspectable node's inspectable children.

 *

 * This annotation can be applied to any getter that returns a collection of objects, either an

 * array, an {@link Iterable} or a {@link java.util.Iterator}. The getter may return null, which

 * will be treated as an empty collection. Additionally, the inspector will discard any null

 * entries in the collection.

 *

 * By default, this annotation is inherited. At runtime, the inspector introspects on the class

 * hierachy and uses the annotated getter from the bottommost class, if different from any

 * annoated getters of the parent class. If a class inherits from a parent class with an annotated

 * getter, but does not include this annotation, the child class will be traversed using the

 * getter annotated on the parent. This holds true even if the child class overrides the getter.

 *

 * @see InspectionHelper#traverseChildren(Object, ChildTraverser)

 * @see InspectionHelper#hasChildTraversal()

 * @hide

 */

@Target({METHOD})

@Retention(SOURCE)

public @interface InspectableChildren {

}

/*

 * 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 static java.lang.annotation.ElementType.TYPE;

import static java.lang.annotation.RetentionPolicy.SOURCE;

import java.lang.annotation.Retention;

import java.lang.annotation.Target;

/**

 * Marks the node name to display to a developer in the inspection tree.

 *

 * This annotation is optional to marking a class as inspectable. If it is omitted, the node name

 * will be inferred using the semantics of {@link Class#getSimpleName()}. The fully qualified class

 * name is always available in the tree, this is for display purposes only. If a class is inflated

 * from XML and the tag it inflates from does not match its simple name, this annotation should be

 * used to inform the inspector to display the XML tag name in the inspection tree view.

 *

 * This annotation does not inherit. If a class extends an annotated parent class, but does not

 * annotate itself, its node name will be inferred from its Java name.

 *

 * @see InspectionHelper#getNodeName()

 * @hide

 */

@Target({TYPE})

@Retention(SOURCE)

public @interface InspectableNodeName {

    /**

     * The display name for nodes of this type.

     *

     * @return The name for nodes of this type

     */

    String value();

}

/*

 * 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 static java.lang.annotation.ElementType.METHOD;

import static java.lang.annotation.RetentionPolicy.SOURCE;

import java.lang.annotation.Retention;

import java.lang.annotation.Target;

/**

 * Marks a getter of a property on an inspectable node.

 *

 * This annotation is inherited by default. If a child class doesn't add it to a getter, but a

 * parent class does, the property will be inspected, even if the child overrides the definition

 * of the getter. If a child class defines a property of the same name of a property on the parent

 * but on a different getter, the inspector will use the child's getter when inspecting instances

 * of the child, and the parent's otherwise.

 *

 * @see InspectionHelper#mapProperties(PropertyMapper)

 * @see InspectionHelper#readProperties(Object, PropertyReader)

 * @hide

 */

@Target({METHOD})

@Retention(SOURCE)

public @interface InspectableProperty {

    /**

     * The name of the property.

     *

     * If left empty (the default), the property name will be inferred from the name of the getter

     * method.

     *

     * @return The name of the property.

     */

    String value() default "";

}