    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 *      https://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.commons.lang3;
    018
    019import java.lang.annotation.Annotation;
    020import java.lang.reflect.Method;
    021import java.util.Arrays;
    022
    023import org.apache.commons.lang3.builder.ToStringBuilder;
    024import org.apache.commons.lang3.builder.ToStringStyle;
    025import org.apache.commons.lang3.exception.UncheckedException;
    026
    027/**
    028 * Helper methods for working with {@link Annotation} instances.
    029 *
    030 * <p>This class contains various utility methods that make working with
    031 * annotations simpler.</p>
    032 *
    033 * <p>{@link Annotation} instances are always proxy objects; unfortunately
    034 * dynamic proxies cannot be depended upon to know how to implement certain
    035 * methods in the same manner as would be done by "natural" {@link Annotation}s.
    036 * The methods presented in this class can be used to avoid that possibility. It
    037 * is of course also possible for dynamic proxies to actually delegate their
    038 * e.g. {@link Annotation#equals(Object)}/{@link Annotation#hashCode()}/
    039 * {@link Annotation#toString()} implementations to {@link AnnotationUtils}.</p>
    040 *
    041 * <p>#ThreadSafe#</p>
    042 *
    043 * @since 3.0
    044 */
    045public class AnnotationUtils {
    046
    047    /**
    048     * A style that prints annotations as recommended.
    049     */
    050    private static final ToStringStyle TO_STRING_STYLE = new ToStringStyle() {
    051        /** Serialization version */
    052        private static final long serialVersionUID = 1L;
    053
    054        {
    055            setDefaultFullDetail(true);
    056            setArrayContentDetail(true);
    057            setUseClassName(true);
    058            setUseShortClassName(true);
    059            setUseIdentityHashCode(false);
    060            setContentStart("(");
    061            setContentEnd(")");
    062            setFieldSeparator(", ");
    063            setArrayStart("[");
    064            setArrayEnd("]");
    065        }
    066
    067        /**
    068         * {@inheritDoc}
    069         */
    070        @Override
    071        protected void appendDetail(final StringBuffer buffer, final String fieldName, Object value) {
    072            if (value instanceof Annotation) {
    073                value = AnnotationUtils.toString((Annotation) value);
    074            }
    075            super.appendDetail(buffer, fieldName, value);
    076        }
    077
    078        /**
    079         * {@inheritDoc}
    080         */
    081        @Override
    082        protected String getShortClassName(final Class<?> cls) {
    083            // formatter:off
    084            return ClassUtils.getAllInterfaces(cls).stream().filter(Annotation.class::isAssignableFrom).findFirst()
    085                .map(iface -> "@" + iface.getName())
    086                .orElse(StringUtils.EMPTY);
    087            // formatter:on
    088        }
    089
    090    };
    091
    092    /**
    093     * Helper method for comparing two arrays of annotations.
    094     *
    095     * @param a1 the first array
    096     * @param a2 the second array
    097     * @return a flag whether these arrays are equal
    098     */
    099    private static boolean annotationArrayMemberEquals(final Annotation[] a1, final Annotation[] a2) {
    100        if (a1.length != a2.length) {
    101            return false;
    102        }
    103        for (int i = 0; i < a1.length; i++) {
    104            if (!equals(a1[i], a2[i])) {
    105                return false;
    106            }
    107        }
    108        return true;
    109    }
    110
    111    /**
    112     * Helper method for comparing two objects of an array type.
    113     *
    114     * @param componentType the component type of the array
    115     * @param o1 the first object
    116     * @param o2 the second object
    117     * @return a flag whether these objects are equal
    118     */
    119    private static boolean arrayMemberEquals(final Class<?> componentType, final Object o1, final Object o2) {
    120        if (componentType.isAnnotation()) {
    121            return annotationArrayMemberEquals((Annotation[]) o1, (Annotation[]) o2);
    122        }
    123        if (componentType.equals(Byte.TYPE)) {
    124            return Arrays.equals((byte[]) o1, (byte[]) o2);
    125        }
    126        if (componentType.equals(Short.TYPE)) {
    127            return Arrays.equals((short[]) o1, (short[]) o2);
    128        }
    129        if (componentType.equals(Integer.TYPE)) {
    130            return Arrays.equals((int[]) o1, (int[]) o2);
    131        }
    132        if (componentType.equals(Character.TYPE)) {
    133            return Arrays.equals((char[]) o1, (char[]) o2);
    134        }
    135        if (componentType.equals(Long.TYPE)) {
    136            return Arrays.equals((long[]) o1, (long[]) o2);
    137        }
    138        if (componentType.equals(Float.TYPE)) {
    139            return Arrays.equals((float[]) o1, (float[]) o2);
    140        }
    141        if (componentType.equals(Double.TYPE)) {
    142            return Arrays.equals((double[]) o1, (double[]) o2);
    143        }
    144        if (componentType.equals(Boolean.TYPE)) {
    145            return Arrays.equals((boolean[]) o1, (boolean[]) o2);
    146        }
    147        return Arrays.equals((Object[]) o1, (Object[]) o2);
    148    }
    149
    150    /**
    151     * Helper method for generating a hash code for an array.
    152     *
    153     * @param componentType the component type of the array
    154     * @param o the array
    155     * @return a hash code for the specified array
    156     */
    157    private static int arrayMemberHash(final Class<?> componentType, final Object o) {
    158        if (componentType.equals(Byte.TYPE)) {
    159            return Arrays.hashCode((byte[]) o);
    160        }
    161        if (componentType.equals(Short.TYPE)) {
    162            return Arrays.hashCode((short[]) o);
    163        }
    164        if (componentType.equals(Integer.TYPE)) {
    165            return Arrays.hashCode((int[]) o);
    166        }
    167        if (componentType.equals(Character.TYPE)) {
    168            return Arrays.hashCode((char[]) o);
    169        }
    170        if (componentType.equals(Long.TYPE)) {
    171            return Arrays.hashCode((long[]) o);
    172        }
    173        if (componentType.equals(Float.TYPE)) {
    174            return Arrays.hashCode((float[]) o);
    175        }
    176        if (componentType.equals(Double.TYPE)) {
    177            return Arrays.hashCode((double[]) o);
    178        }
    179        if (componentType.equals(Boolean.TYPE)) {
    180            return Arrays.hashCode((boolean[]) o);
    181        }
    182        return Arrays.hashCode((Object[]) o);
    183    }
    184
    185    /**
    186     * Checks if two annotations are equal using the criteria for equality
    187     * presented in the {@link Annotation#equals(Object)} API docs.
    188     *
    189     * @param a1 the first Annotation to compare, {@code null} returns
    190     * {@code false} unless both are {@code null}
    191     * @param a2 the second Annotation to compare, {@code null} returns
    192     * {@code false} unless both are {@code null}
    193     * @return {@code true} if the two annotations are {@code equal} or both
    194     * {@code null}
    195     */
    196    public static boolean equals(final Annotation a1, final Annotation a2) {
    197        if (a1 == a2) {
    198            return true;
    199        }
    200        if (a1 == null || a2 == null) {
    201            return false;
    202        }
    203        final Class<? extends Annotation> type1 = a1.annotationType();
    204        final Class<? extends Annotation> type2 = a2.annotationType();
    205        Validate.notNull(type1, "Annotation %s with null annotationType()", a1);
    206        Validate.notNull(type2, "Annotation %s with null annotationType()", a2);
    207        if (!type1.equals(type2)) {
    208            return false;
    209        }
    210        try {
    211            for (final Method m : type1.getDeclaredMethods()) {
    212                if (m.getParameterTypes().length == 0
    213                        && isValidAnnotationMemberType(m.getReturnType())) {
    214                    final Object v1 = m.invoke(a1);
    215                    final Object v2 = m.invoke(a2);
    216                    if (!memberEquals(m.getReturnType(), v1, v2)) {
    217                        return false;
    218                    }
    219                }
    220            }
    221        } catch (final ReflectiveOperationException ex) {
    222            return false;
    223        }
    224        return true;
    225    }
    226
    227    /**
    228     * Generate a hash code for the given annotation using the algorithm
    229     * presented in the {@link Annotation#hashCode()} API docs.
    230     *
    231     * @param a the Annotation for a hash code calculation is desired, not
    232     * {@code null}
    233     * @return the calculated hash code
    234     * @throws RuntimeException if an {@link Exception} is encountered during
    235     * annotation member access
    236     * @throws IllegalStateException if an annotation method invocation returns
    237     * {@code null}
    238     */
    239    public static int hashCode(final Annotation a) {
    240        int result = 0;
    241        final Class<? extends Annotation> type = a.annotationType();
    242        for (final Method m : type.getDeclaredMethods()) {
    243            try {
    244                final Object value = m.invoke(a);
    245                if (value == null) {
    246                    throw new IllegalStateException(String.format("Annotation method %s returned null", m));
    247                }
    248                result += hashMember(m.getName(), value);
    249            } catch (final ReflectiveOperationException ex) {
    250                throw new UncheckedException(ex);
    251            }
    252        }
    253        return result;
    254    }
    255
    256    //besides modularity, this has the advantage of autoboxing primitives:
    257    /**
    258     * Helper method for generating a hash code for a member of an annotation.
    259     *
    260     * @param name the name of the member
    261     * @param value the value of the member
    262     * @return a hash code for this member
    263     */
    264    private static int hashMember(final String name, final Object value) {
    265        final int part1 = name.hashCode() * 127;
    266        if (ObjectUtils.isArray(value)) {
    267            return part1 ^ arrayMemberHash(value.getClass().getComponentType(), value);
    268        }
    269        if (value instanceof Annotation) {
    270            return part1 ^ hashCode((Annotation) value);
    271        }
    272        return part1 ^ value.hashCode();
    273    }
    274
    275    /**
    276     * Checks if the specified type is permitted as an annotation member.
    277     *
    278     * <p>The Java language specification only permits certain types to be used
    279     * in annotations. These include {@link String}, {@link Class}, primitive
    280     * types, {@link Annotation}, {@link Enum}, and single-dimensional arrays of
    281     * these types.</p>
    282     *
    283     * @param type the type to check, {@code null}
    284     * @return {@code true} if the type is a valid type to use in an annotation
    285     */
    286    public static boolean isValidAnnotationMemberType(Class<?> type) {
    287        if (type == null) {
    288            return false;
    289        }
    290        if (type.isArray()) {
    291            type = type.getComponentType();
    292        }
    293        return type.isPrimitive() || type.isEnum() || type.isAnnotation()
    294                || String.class.equals(type) || Class.class.equals(type);
    295    }
    296
    297    /**
    298     * Helper method for checking whether two objects of the given type are
    299     * equal. This method is used to compare the parameters of two annotation
    300     * instances.
    301     *
    302     * @param type the type of the objects to be compared
    303     * @param o1 the first object
    304     * @param o2 the second object
    305     * @return a flag whether these objects are equal
    306     */
    307    private static boolean memberEquals(final Class<?> type, final Object o1, final Object o2) {
    308        if (o1 == o2) {
    309            return true;
    310        }
    311        if (o1 == null || o2 == null) {
    312            return false;
    313        }
    314        if (type.isArray()) {
    315            return arrayMemberEquals(type.getComponentType(), o1, o2);
    316        }
    317        if (type.isAnnotation()) {
    318            return equals((Annotation) o1, (Annotation) o2);
    319        }
    320        return o1.equals(o2);
    321    }
    322
    323    /**
    324     * Generate a string representation of an Annotation, as suggested by
    325     * {@link Annotation#toString()}.
    326     *
    327     * @param a the annotation of which a string representation is desired
    328     * @return the standard string representation of an annotation, not
    329     * {@code null}
    330     */
    331    public static String toString(final Annotation a) {
    332        final ToStringBuilder builder = new ToStringBuilder(a, TO_STRING_STYLE);
    333        for (final Method m : a.annotationType().getDeclaredMethods()) {
    334            if (m.getParameterTypes().length > 0) {
    335                continue; // what?
    336            }
    337            try {
    338                builder.append(m.getName(), m.invoke(a));
    339            } catch (final ReflectiveOperationException ex) {
    340                throw new UncheckedException(ex);
    341            }
    342        }
    343        return builder.build();
    344    }
    345
    346    /**
    347     * {@link AnnotationUtils} instances should NOT be constructed in
    348     * standard programming. Instead, the class should be used statically.
    349     *
    350     * <p>This constructor is public to permit tools that require a JavaBean
    351     * instance to operate.</p>
    352     * @deprecated TODO Make private in 4.0.
    353     */
    354    @Deprecated
    355    public AnnotationUtils() {
    356        // empty
    357    }
    358}