/*
 * Copyright 2002-2015 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.aop.aspectj.annotation;

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

import org.aopalliance.aop.Advice;

import org.springframework.aop.Advisor;
import org.springframework.aop.aspectj.AspectJExpressionPointcut;
import org.springframework.aop.framework.AopConfigException;
import org.springframework.lang.Nullable;

Interface for factories that can create Spring AOP Advisors from classes
annotated with AspectJ annotation syntax.
Author:
Rod Johnson, Juergen Hoeller
See Also:
AspectMetadata
AjTypeSystem
Since:
2.0/**
 * Interface for factories that can create Spring AOP Advisors from classes
 * annotated with AspectJ annotation syntax.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @since 2.0
 * @see AspectMetadata
 * @see org.aspectj.lang.reflect.AjTypeSystem
 */
public interface AspectJAdvisorFactory {

	
Determine whether or not the given class is an aspect, as reported by AspectJ's AjTypeSystem. 
Will simply return false if the supposed aspect is invalid (such as an extension of a concrete aspect class). Will return true for some aspects that Spring AOP cannot process, such as those with unsupported instantiation models. Use the validate method to handle these cases if necessary. 
Params:
clazz – the supposed annotation-style AspectJ class
Returns:
whether or not this class is recognized by AspectJ as an aspect class/**
	 * Determine whether or not the given class is an aspect, as reported
	 * by AspectJ's {@link org.aspectj.lang.reflect.AjTypeSystem}.
	 * <p>Will simply return {@code false} if the supposed aspect is
	 * invalid (such as an extension of a concrete aspect class).
	 * Will return true for some aspects that Spring AOP cannot process,
	 * such as those with unsupported instantiation models.
	 * Use the {@link #validate} method to handle these cases if necessary.
	 * @param clazz the supposed annotation-style AspectJ class
	 * @return whether or not this class is recognized by AspectJ as an aspect class
	 */
	boolean isAspect(Class<?> clazz);

	
Is the given class a valid AspectJ aspect class?
Params:
aspectClass – the supposed AspectJ annotation-style class to validate
Throws:
AopConfigException – if the class is an invalid aspect
(which can never be legal)
NotAnAtAspectException – if the class is not an aspect at all
(which may or may not be legal, depending on the context)/**
	 * Is the given class a valid AspectJ aspect class?
	 * @param aspectClass the supposed AspectJ annotation-style class to validate
	 * @throws AopConfigException if the class is an invalid aspect
	 * (which can never be legal)
	 * @throws NotAnAtAspectException if the class is not an aspect at all
	 * (which may or may not be legal, depending on the context)
	 */
	void validate(Class<?> aspectClass) throws AopConfigException;

	
Build Spring AOP Advisors for all annotated At-AspectJ methods
on the specified aspect instance.
Params:
aspectInstanceFactory – the aspect instance factory
(not the aspect instance itself in order to avoid eager instantiation)
Returns:
a list of advisors for this class/**
	 * Build Spring AOP Advisors for all annotated At-AspectJ methods
	 * on the specified aspect instance.
	 * @param aspectInstanceFactory the aspect instance factory
	 * (not the aspect instance itself in order to avoid eager instantiation)
	 * @return a list of advisors for this class
	 */
	List<Advisor> getAdvisors(MetadataAwareAspectInstanceFactory aspectInstanceFactory);

	
Build a Spring AOP Advisor for the given AspectJ advice method.
Params:
candidateAdviceMethod – the candidate advice method
aspectInstanceFactory – the aspect instance factory
declarationOrder – the declaration order within the aspect
aspectName – the name of the aspect
Returns:
null if the method is not an AspectJ advice method or if it is a pointcut that will be used by other advice but will not create a Spring advice in its own right/**
	 * Build a Spring AOP Advisor for the given AspectJ advice method.
	 * @param candidateAdviceMethod the candidate advice method
	 * @param aspectInstanceFactory the aspect instance factory
	 * @param declarationOrder the declaration order within the aspect
	 * @param aspectName the name of the aspect
	 * @return {@code null} if the method is not an AspectJ advice method
	 * or if it is a pointcut that will be used by other advice but will not
	 * create a Spring advice in its own right
	 */
	@Nullable
	Advisor getAdvisor(Method candidateAdviceMethod, MetadataAwareAspectInstanceFactory aspectInstanceFactory,
			int declarationOrder, String aspectName);

	
Build a Spring AOP Advice for the given AspectJ advice method.
Params:
candidateAdviceMethod – the candidate advice method
expressionPointcut – the AspectJ expression pointcut
aspectInstanceFactory – the aspect instance factory
declarationOrder – the declaration order within the aspect
aspectName – the name of the aspect
See Also:
AspectJAroundAdvice
AspectJMethodBeforeAdvice
AspectJAfterAdvice
AspectJAfterReturningAdvice
AspectJAfterThrowingAdvice
Returns:
null if the method is not an AspectJ advice method or if it is a pointcut that will be used by other advice but will not create a Spring advice in its own right/**
	 * Build a Spring AOP Advice for the given AspectJ advice method.
	 * @param candidateAdviceMethod the candidate advice method
	 * @param expressionPointcut the AspectJ expression pointcut
	 * @param aspectInstanceFactory the aspect instance factory
	 * @param declarationOrder the declaration order within the aspect
	 * @param aspectName the name of the aspect
	 * @return {@code null} if the method is not an AspectJ advice method
	 * or if it is a pointcut that will be used by other advice but will not
	 * create a Spring advice in its own right
	 * @see org.springframework.aop.aspectj.AspectJAroundAdvice
	 * @see org.springframework.aop.aspectj.AspectJMethodBeforeAdvice
	 * @see org.springframework.aop.aspectj.AspectJAfterAdvice
	 * @see org.springframework.aop.aspectj.AspectJAfterReturningAdvice
	 * @see org.springframework.aop.aspectj.AspectJAfterThrowingAdvice
	 */
	@Nullable
	Advice getAdvice(Method candidateAdviceMethod, AspectJExpressionPointcut expressionPointcut,
			MetadataAwareAspectInstanceFactory aspectInstanceFactory, int declarationOrder, String aspectName);

}