001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.reflect;
018
019/**
020 * Interface for all annotatable wrapper classes.
021 *
022 * <p>
023 * This interface provides a common type for all wrappers around Java reflection objects,
024 * allowing polymorphic handling of different annotatable types (Class, Method, Field, Constructor, Parameter, Package).
025 *
026 * <p>
027 * Implementers include:
028 * <ul>
029 *    <li>{@link ClassInfo} - Wraps {@link Class}
030 *    <li>{@link MethodInfo} - Wraps {@link java.lang.reflect.Method}
031 *    <li>{@link FieldInfo} - Wraps {@link java.lang.reflect.Field}
032 *    <li>{@link ConstructorInfo} - Wraps {@link java.lang.reflect.Constructor}
033 *    <li>{@link ParameterInfo} - Wraps {@link java.lang.reflect.Parameter}
034 *    <li>{@link PackageInfo} - Wraps {@link java.lang.Package}
035 * </ul>
036 */
037public interface Annotatable {
038
039   /**
040    * Returns the type of this annotatable object.
041    *
042    * @return The type of annotatable object this represents.
043    */
044   AnnotatableType getAnnotatableType();
045
046   /**
047    * Returns a human-readable label for this annotatable element.
048    *
049    * <p>
050    * The label format depends on the type of annotatable:
051    * <ul>
052    *    <li>{@link AnnotatableType#CLASS_TYPE CLASS_TYPE} - Simple class name (e.g., <js>"MyClass"</js>)
053    *    <li>{@link AnnotatableType#METHOD_TYPE METHOD_TYPE} - Class and method with parameter types (e.g., <js>"MyClass.myMethod(String,int)"</js>)
054    *    <li>{@link AnnotatableType#FIELD_TYPE FIELD_TYPE} - Class and field name (e.g., <js>"MyClass.myField"</js>)
055    *    <li>{@link AnnotatableType#CONSTRUCTOR_TYPE CONSTRUCTOR_TYPE} - Class and constructor with parameter types (e.g., <js>"MyClass.MyClass(String)"</js>)
056    *    <li>{@link AnnotatableType#PARAMETER_TYPE PARAMETER_TYPE} - Class, method/constructor, and parameter index (e.g., <js>"MyClass.myMethod[0]"</js>)
057    *    <li>{@link AnnotatableType#PACKAGE_TYPE PACKAGE_TYPE} - Package name (e.g., <js>"com.example.package"</js>)
058    * </ul>
059    *
060    * @return The human-readable label for this annotatable element.
061    */
062   String getLabel();
063}