• Home
• com.github.blindpirate
• annotation-magic
• 0.2.3
• source code
• AnnotationMagic.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.github.blindpirate.annotationmagic.AnnotationMagic Maven / Gradle / Ivy

package com.github.blindpirate.annotationmagic;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.util.List;

/**
 * The main entry point for AnnotationMagic library, which retrieves Java annotations "in the magic way".
 * It supports annotation inheritance and composition.
 *
 * See the documentation on GitHub for more details.
 *
 * All operations in this class is fully cached by default. See {@link AnnotationMagician#cache}.
 */
public class AnnotationMagic {
    private static final AnnotationMagician INSTANCE = new AnnotationMagician();

    /**
     * Returns the annotation of the specified {@code annotationClass} type on {@code targetClass} in the magic way
     * if and only if one annotation can be found, or else null. If more than one annotation is found, an
     * exception will be thrown.
     *
     * @param targetClass the target class to be searched for annotations
     * @param annotationClass the Class object corresponding to the annotation type
     * @param  the type of the annotation to query for and return if present
     * @return the target class' annotation for the specified annotation type if and only if one present on this element, else null
     * @since 0.1
     */
    public static  A getOneAnnotationOnClassOrNull(Class targetClass, Class annotationClass) {
        return INSTANCE.getOneAnnotationOnClassOrNull(targetClass, annotationClass);
    }

    /**
     * Returns the annotation of the specified {@code annotationClass} type on {@code method} in the magic way
     * if and only if one annotation can be found, or else null. If more than one annotation is found, an
     * exception will be thrown.
     *
     * @param method the target method to be searched for annotations
     * @param annotationClass the Class object corresponding to the annotation type
     * @param  the type of the annotation to query for and return if present
     * @return the target method's annotation for the specified annotation type if one present on this element, else null
     * @since 0.1
     */
    public static  A getOneAnnotationOnMethodOrNull(Method method, Class annotationClass) {
        return INSTANCE.getOneAnnotationOnMethodOrNull(method, annotationClass);
    }

    /**
     * Returns all annotations of the specified {@code annotationClass} type on {@code method} in the magic way.
     * If no such annotations are found, an empty {@code List} will be returned.
     *
     * @param method the target method to be searched for annotations
     * @param annotationClass the Class object corresponding to the annotation type
     * @param  the type of the annotation to query for and return if present
     * @return the target method's annotations for the specified annotation type, empty if no such annotations found
     * @since 0.1
     */
    public static  List getAnnotationsOnMethod(Method method, Class annotationClass) {
        return INSTANCE.getAnnotationsOnMethod(method, annotationClass);
    }

    /**
     * Returns the annotation of the specified {@code annotationClass} type on {@code targetClass} in the magic way.
     * If no such annotations are found, an empty {@code List} will be returned.
     *
     * @param targetClass the target class to be searched for annotations
     * @param annotationClass the Class object corresponding to the annotation type
     * @param  the type of the annotation to query for and return if present
     * @return the target class' annotations for the specified annotation type, empty if no such annotations found
     * @since 0.1
     */
    public static  List getAnnotationsOnClass(Class targetClass, Class annotationClass) {
        return INSTANCE.getAnnotationsOnClass(targetClass, annotationClass);
    }

    /**
     * Returns the annotation of the specified {@code annotationClass} type on {@code method}'s {@code i}th parameter in the magic way
     * if and only if one annotation can be found, or else null. If more than one annotation is found, an
     * exception will be thrown.
     *
     * @param method the target method to be searched for annotations
     * @param i the index of target parameter in target method's parameter list
     * @param annotationClass the Class object corresponding to the annotation type
     * @param  the type of the annotation to query for and return if present
     * @return the annotation for the specified annotation type if and only one present on the method's ith parameter, else null
     * @since 0.1
     */
    public static  A getOneAnnotationOnMethodParameterOrNull(Method method, int i, Class annotationClass) {
        return INSTANCE.getOneAnnotationOnMethodParameterOrNull(method, i, annotationClass);
    }

    /**
     * Returns {@code true} if an annotation is subtype of specified {@code klass} annotation type in the magic way, {@code false} otherwise.
     * It's similar to normal {@code instanceof} operator, but works for annotations.
     *
     * @param annotation the annotation instance corresponding to the left operand of {@code instanceof}
     * @param klass the Class object corresponding to the right operand of {@code instanceof}
     * @return {@code true} if an annotation is subtype of specified {@code klass} annotation type in the magic way, {@code false} otherwise
     */
    public static boolean instanceOf(Annotation annotation, Class klass) {
        return INSTANCE.instanceOf(annotation, klass);
    }

    /**
     * Cast an annotation to its super annotation in the magic way. You should make sure {@link #instanceOf(Annotation, Class)} returns true
     * on the parameters, otherwise a {@link ClassCastException} will be thrown.
     *
     * @param annotation the annotation to be cast
     * @param targetAnnotation the class instance of the annotation type to be cast to
     * @param  the annotation type to be cast to
     * @return the cast result. A {@link ClassCastException} will be thrown if the cast can't be performed,
     */
    public static  A cast(Annotation annotation, Class targetAnnotation) {
        return INSTANCE.cast(annotation, targetAnnotation);
    }

    /**
     * Returns {@code true} the annotation of the specified {@code annotationClass} type is present on {@code targetClass} in the magic way,
     * {@code false} otherwise.
     *
     * @param targetClass the target class to be searched for annotations
     * @param annotationClass the Class object corresponding to the annotation type
     * @return {@code true} the annotation of the specified {@code annotationClass} type is present on {@code targetClass} in the magic way,
     * {@code false} otherwise
     */
    public static boolean isAnnotationPresent(Class targetClass, Class annotationClass) {
        return INSTANCE.isAnnotationPresent(targetClass, annotationClass);
    }

    /**
     * Returns {@code true} the annotation of the specified {@code annotationClass} type is present on the target {@code method} in the magic way,
     * {@code false} otherwise.
     *
     * @param method the target method to be searched for annotations
     * @param annotationClass the Class object corresponding to the annotation type
     * @return {@code true} the annotation of the specified {@code annotationClass} type is present on the target {@code method} in the magic way,
     * {@code false} otherwise
     */
    public static boolean isAnnotationPresent(Method method, Class annotationClass) {
        return INSTANCE.isAnnotationPresent(method, annotationClass);
    }
}