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
019import java.lang.reflect.*;
020
021/**
022 * Utility class providing convenient static methods for creating reflection info objects.
023 *
024 * <p>
025 * This class provides static factory methods that convert standard Java reflection objects
026 * ({@link Class}, {@link Method}, {@link Field}, {@link Constructor}) to their corresponding
027 * info wrapper objects ({@link ClassInfo}, {@link MethodInfo}, {@link FieldInfo}, {@link ConstructorInfo}).
028 *
029 * <h5 class='section'>Features:</h5>
030 * <ul class='spaced-list'>
031 *    <li>Convenient factory methods - convert reflection objects to info wrappers
032 *    <li>Null-safe - methods handle <jk>null</jk> inputs gracefully
033 *    <li>Unified API - consistent method naming across all reflection types
034 * </ul>
035 *
036 * <h5 class='section'>Use Cases:</h5>
037 * <ul class='spaced-list'>
038 *    <li>Converting reflection objects to info wrappers in a consistent way
039 *    <li>Simplifying code that works with both reflection and info objects
040 *    <li>Providing a centralized location for reflection-to-info conversions
041 * </ul>
042 *
043 * <h5 class='section'>Usage:</h5>
044 * <p class='bjava'>
045 *    <jc>// Convert Class to ClassInfo</jc>
046 *    ClassInfo <jv>ci</jv> = ReflectionUtils.<jsm>info</jsm>(MyClass.<jk>class</jk>);
047 *
048 *    <jc>// Convert Method to MethodInfo</jc>
049 *    Method <jv>m</jv> = MyClass.<jk>class</jk>.getMethod(<js>"myMethod"</js>);
050 *    MethodInfo <jv>mi</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>m</jv>);
051 *
052 *    <jc>// Convert Field to FieldInfo</jc>
053 *    Field <jv>f</jv> = MyClass.<jk>class</jk>.getField(<js>"myField"</js>);
054 *    FieldInfo <jv>fi</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>f</jv>);
055 *
056 *    <jc>// Convert Constructor to ConstructorInfo</jc>
057 *    Constructor&lt;?&gt; <jv>c</jv> = MyClass.<jk>class</jk>.getConstructor();
058 *    ConstructorInfo <jv>ci2</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>c</jv>);
059 * </p>
060 *
061 * <h5 class='section'>Null Handling:</h5>
062 * <p>
063 * All methods in this class handle <jk>null</jk> inputs gracefully, returning <jk>null</jk> if the
064 * input is <jk>null</jk>. This makes it safe to use in scenarios where reflection objects may be <jk>null</jk>.
065 *
066 * <h5 class='section'>See Also:</h5><ul>
067 *    <li class='jc'>{@link ClassInfo} - Class introspection wrapper
068 *    <li class='jc'>{@link MethodInfo} - Method introspection wrapper
069 *    <li class='jc'>{@link FieldInfo} - Field introspection wrapper
070 *    <li class='jc'>{@link ConstructorInfo} - Constructor introspection wrapper
071 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauCommonsReflection">Reflection Package</a>
072 * </ul>
073 */
074public class ReflectionUtils {
075
076   /**
077    * Returns the {@link ClassInfo} wrapper for the specified class.
078    *
079    * <h5 class='section'>Example:</h5>
080    * <p class='bjava'>
081    *    ClassInfo <jv>ci</jv> = ReflectionUtils.<jsm>info</jsm>(MyClass.<jk>class</jk>);
082    * </p>
083    *
084    * @param o The class to wrap. Can be <jk>null</jk>.
085    * @return The {@link ClassInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
086    */
087   public static final <T> ClassInfoTyped<T> info(Class<T> o) {
088      return ClassInfo.of(o);
089   }
090
091   /**
092    * Returns the {@link ConstructorInfo} wrapper for the specified constructor.
093    *
094    * <h5 class='section'>Example:</h5>
095    * <p class='bjava'>
096    *    Constructor&lt;?&gt; <jv>c</jv> = MyClass.<jk>class</jk>.getConstructor();
097    *    ConstructorInfo <jv>ci</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>c</jv>);
098    * </p>
099    *
100    * @param o The constructor to wrap. Can be <jk>null</jk>.
101    * @return The {@link ConstructorInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
102    */
103   public static final ConstructorInfo info(Constructor<?> o) {
104      return ConstructorInfo.of(o);
105   }
106
107   /**
108    * Returns the {@link FieldInfo} wrapper for the specified field.
109    *
110    * <h5 class='section'>Example:</h5>
111    * <p class='bjava'>
112    *    Field <jv>f</jv> = MyClass.<jk>class</jk>.getField(<js>"myField"</js>);
113    *    FieldInfo <jv>fi</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>f</jv>);
114    * </p>
115    *
116    * @param o The field to wrap. Can be <jk>null</jk>.
117    * @return The {@link FieldInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
118    */
119   public static final FieldInfo info(Field o) {
120      return FieldInfo.of(o);
121   }
122
123   /**
124    * Returns the {@link MethodInfo} wrapper for the specified method.
125    *
126    * <h5 class='section'>Example:</h5>
127    * <p class='bjava'>
128    *    Method <jv>m</jv> = MyClass.<jk>class</jk>.getMethod(<js>"myMethod"</js>);
129    *    MethodInfo <jv>mi</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>m</jv>);
130    * </p>
131    *
132    * @param o The method to wrap. Can be <jk>null</jk>.
133    * @return The {@link MethodInfo} wrapper, or <jk>null</jk> if the input is <jk>null</jk>.
134    */
135   public static final MethodInfo info(Method o) {
136      return MethodInfo.of(o);
137   }
138
139   /**
140    * Returns the {@link ClassInfo} wrapper for the class of the specified object.
141    *
142    * <h5 class='section'>Example:</h5>
143    * <p class='bjava'>
144    *    MyClass <jv>obj</jv> = <jk>new</jk> MyClass();
145    *    ClassInfo <jv>ci</jv> = ReflectionUtils.<jsm>info</jsm>(<jv>obj</jv>);
146    * </p>
147    *
148    * @param o The object whose class to wrap. Can be <jk>null</jk>.
149    * @return The {@link ClassInfo} wrapper for the object's class, or <jk>null</jk> if the input is <jk>null</jk>.
150    */
151   public static final ClassInfo info(Object o) {
152      return ClassInfo.of(o);
153   }
154}