package org.testng.internal.annotations;

import java.lang.reflect.Constructor;
import java.lang.reflect.Method;

import org.testng.ITestNGMethod;
import org.testng.annotations.IAnnotation;
import org.testng.internal.ConstructorOrMethod;

This interface defines how annotations are found on classes, methods and constructors. It will be
implemented by both JDK 1.4 and JDK 5 annotation finders.
/**
 * This interface defines how annotations are found on classes, methods and constructors. It will be
 * implemented by both JDK 1.4 and JDK 5 annotation finders.
 */
public interface IAnnotationFinder {

  
Params:
cls – - The corresponding class.
annotationClass – - The class on which annotation is to be looked for.
Type parameters:
<A> – The expected IAnnotation type
Returns:
The annotation on the class or null if none found./**
   * @param cls - The corresponding class.
   * @param annotationClass - The class on which annotation is to be looked for.
   * @param <A> The expected {@link IAnnotation} type
   * @return The annotation on the class or null if none found.
   */
  <A extends IAnnotation> A findAnnotation(Class<?> cls, Class<A> annotationClass);

  
Params:
m – - The corresponding Method
annotationClass – - The class on which annotation is to be looked for.
Type parameters:
<A> – The expected IAnnotation type
Returns:
The annotation on the method. If not found, return the annotation on the declaring
    class. If not found, return null./**
   * @param m - The corresponding {@link Method}
   * @param annotationClass - The class on which annotation is to be looked for.
   * @param <A> The expected {@link IAnnotation} type
   * @return The annotation on the method. If not found, return the annotation on the declaring
   *     class. If not found, return null.
   */
  <A extends IAnnotation> A findAnnotation(Method m, Class<A> annotationClass);

  <A extends IAnnotation> A findAnnotation(ITestNGMethod m, Class<A> annotationClass);

  <A extends IAnnotation> A findAnnotation(ConstructorOrMethod com, Class<A> annotationClass);

  <A extends IAnnotation> A findAnnotation(
      Class<?> clazz, Method m, java.lang.Class<A> annotationClass);

  
Params:
cons – - The corresponding Constructor
annotationClass – - The class on which annotation is to be looked for.
Type parameters:
<A> – The expected IAnnotation type
Returns:
The annotation on the method. If not found, return the annotation on the declaring
    class. If not found, return null./**
   * @param cons - The corresponding {@link Constructor}
   * @param annotationClass - The class on which annotation is to be looked for.
   * @param <A> The expected {@link IAnnotation} type
   * @return The annotation on the method. If not found, return the annotation on the declaring
   *     class. If not found, return null.
   */
  <A extends IAnnotation> A findAnnotation(Constructor<?> cons, Class<A> annotationClass);

  
Params:
method – The Method
i – The parameter index
Returns:
true if the ith parameter of the given method has the annotation @TestInstance./**
   * @param method The <code>Method</code>
   * @param i The parameter index
   * @return true if the ith parameter of the given method has the annotation @TestInstance.
   */
  boolean hasTestInstance(Method method, int i);

  
Params:
method – The Method
Returns:
the @Optional values of this method's parameters (null if the parameter
    isn't optional)/**
   * @param method The <code>Method</code>
   * @return the @Optional values of this method's parameters (<code>null</code> if the parameter
   *     isn't optional)
   */
  String[] findOptionalValues(Method method);

  
Params:
ctor – The Constructor
Returns:
the @Optional values of this method's parameters (null if the parameter
    isn't optional)/**
   * @param ctor The <code>Constructor</code>
   * @return the @Optional values of this method's parameters (<code>null</code> if the parameter
   *     isn't optional)
   */
  String[] findOptionalValues(Constructor<?> ctor);
}