Java tutorial
/* * Copyright 2002-2019 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.beans.factory.config; import java.io.IOException; import java.io.ObjectInputStream; import java.io.Serializable; import java.lang.annotation.Annotation; import java.lang.reflect.Field; import java.lang.reflect.ParameterizedType; import java.lang.reflect.Type; import java.util.Map; import java.util.Optional; import kotlin.reflect.KProperty; import kotlin.reflect.jvm.ReflectJvmMapping; import org.springframework.beans.BeansException; import org.springframework.beans.factory.BeanFactory; import org.springframework.beans.factory.InjectionPoint; import org.springframework.beans.factory.NoUniqueBeanDefinitionException; import org.springframework.core.KotlinDetector; import org.springframework.core.MethodParameter; import org.springframework.core.ParameterNameDiscoverer; import org.springframework.core.ResolvableType; import org.springframework.core.convert.TypeDescriptor; import org.springframework.lang.Nullable; import org.springframework.util.ObjectUtils; /** * Descriptor for a specific dependency that is about to be injected. * Wraps a constructor parameter, a method parameter or a field, * allowing unified access to their metadata. * * @author Juergen Hoeller * @since 2.5 */ @SuppressWarnings("serial") public class DependencyDescriptor extends InjectionPoint implements Serializable { private final Class<?> declaringClass; @Nullable private String methodName; @Nullable private Class<?>[] parameterTypes; private int parameterIndex; @Nullable private String fieldName; private final boolean required; private final boolean eager; private int nestingLevel = 1; @Nullable private Class<?> containingClass; @Nullable private transient volatile ResolvableType resolvableType; @Nullable private transient volatile TypeDescriptor typeDescriptor; /** * Create a new descriptor for a method or constructor parameter. * Considers the dependency as 'eager'. * @param methodParameter the MethodParameter to wrap * @param required whether the dependency is required */ public DependencyDescriptor(MethodParameter methodParameter, boolean required) { this(methodParameter, required, true); } /** * Create a new descriptor for a method or constructor parameter. * @param methodParameter the MethodParameter to wrap * @param required whether the dependency is required * @param eager whether this dependency is 'eager' in the sense of * eagerly resolving potential target beans for type matching */ public DependencyDescriptor(MethodParameter methodParameter, boolean required, boolean eager) { super(methodParameter); this.declaringClass = methodParameter.getDeclaringClass(); if (methodParameter.getMethod() != null) { this.methodName = methodParameter.getMethod().getName(); } this.parameterTypes = methodParameter.getExecutable().getParameterTypes(); this.parameterIndex = methodParameter.getParameterIndex(); this.containingClass = methodParameter.getContainingClass(); this.required = required; this.eager = eager; } /** * Create a new descriptor for a field. * Considers the dependency as 'eager'. * @param field the field to wrap * @param required whether the dependency is required */ public DependencyDescriptor(Field field, boolean required) { this(field, required, true); } /** * Create a new descriptor for a field. * @param field the field to wrap * @param required whether the dependency is required * @param eager whether this dependency is 'eager' in the sense of * eagerly resolving potential target beans for type matching */ public DependencyDescriptor(Field field, boolean required, boolean eager) { super(field); this.declaringClass = field.getDeclaringClass(); this.fieldName = field.getName(); this.required = required; this.eager = eager; } /** * Copy constructor. * @param original the original descriptor to create a copy from */ public DependencyDescriptor(DependencyDescriptor original) { super(original); this.declaringClass = original.declaringClass; this.methodName = original.methodName; this.parameterTypes = original.parameterTypes; this.parameterIndex = original.parameterIndex; this.fieldName = original.fieldName; this.containingClass = original.containingClass; this.required = original.required; this.eager = original.eager; this.nestingLevel = original.nestingLevel; } /** * Return whether this dependency is required. * <p>Optional semantics are derived from Java 8's {@link java.util.Optional}, * any variant of a parameter-level {@code Nullable} annotation (such as from * JSR-305 or the FindBugs set of annotations), or a language-level nullable * type declaration in Kotlin. */ public boolean isRequired() { if (!this.required) { return false; } if (this.field != null) { return !(this.field.getType() == Optional.class || hasNullableAnnotation() || (KotlinDetector.isKotlinReflectPresent() && KotlinDetector.isKotlinType(this.field.getDeclaringClass()) && KotlinDelegate.isNullable(this.field))); } else { return !obtainMethodParameter().isOptional(); } } /** * Check whether the underlying field is annotated with any variant of a * {@code Nullable} annotation, e.g. {@code javax.annotation.Nullable} or * {@code edu.umd.cs.findbugs.annotations.Nullable}. */ private boolean hasNullableAnnotation() { for (Annotation ann : getAnnotations()) { if ("Nullable".equals(ann.annotationType().getSimpleName())) { return true; } } return false; } /** * Return whether this dependency is 'eager' in the sense of * eagerly resolving potential target beans for type matching. */ public boolean isEager() { return this.eager; } /** * Resolve the specified not-unique scenario: by default, * throwing a {@link NoUniqueBeanDefinitionException}. * <p>Subclasses may override this to select one of the instances or * to opt out with no result at all through returning {@code null}. * @param type the requested bean type * @param matchingBeans a map of bean names and corresponding bean * instances which have been pre-selected for the given type * (qualifiers etc already applied) * @return a bean instance to proceed with, or {@code null} for none * @throws BeansException in case of the not-unique scenario being fatal * @since 5.1 */ @Nullable public Object resolveNotUnique(ResolvableType type, Map<String, Object> matchingBeans) throws BeansException { throw new NoUniqueBeanDefinitionException(type, matchingBeans.keySet()); } /** * Resolve the specified not-unique scenario: by default, * throwing a {@link NoUniqueBeanDefinitionException}. * <p>Subclasses may override this to select one of the instances or * to opt out with no result at all through returning {@code null}. * @param type the requested bean type * @param matchingBeans a map of bean names and corresponding bean * instances which have been pre-selected for the given type * (qualifiers etc already applied) * @return a bean instance to proceed with, or {@code null} for none * @throws BeansException in case of the not-unique scenario being fatal * @since 4.3 * @deprecated as of 5.1, in favor of {@link #resolveNotUnique(ResolvableType, Map)} */ @Deprecated @Nullable public Object resolveNotUnique(Class<?> type, Map<String, Object> matchingBeans) throws BeansException { throw new NoUniqueBeanDefinitionException(type, matchingBeans.keySet()); } /** * Resolve a shortcut for this dependency against the given factory, for example * taking some pre-resolved information into account. * <p>The resolution algorithm will first attempt to resolve a shortcut through this * method before going into the regular type matching algorithm across all beans. * Subclasses may override this method to improve resolution performance based on * pre-cached information while still receiving {@link InjectionPoint} exposure etc. * @param beanFactory the associated factory * @return the shortcut result if any, or {@code null} if none * @throws BeansException if the shortcut could not be obtained * @since 4.3.1 */ @Nullable public Object resolveShortcut(BeanFactory beanFactory) throws BeansException { return null; } /** * Resolve the specified bean name, as a candidate result of the matching * algorithm for this dependency, to a bean instance from the given factory. * <p>The default implementation calls {@link BeanFactory#getBean(String)}. * Subclasses may provide additional arguments or other customizations. * @param beanName the bean name, as a candidate result for this dependency * @param requiredType the expected type of the bean (as an assertion) * @param beanFactory the associated factory * @return the bean instance (never {@code null}) * @throws BeansException if the bean could not be obtained * @since 4.3.2 * @see BeanFactory#getBean(String) */ public Object resolveCandidate(String beanName, Class<?> requiredType, BeanFactory beanFactory) throws BeansException { return beanFactory.getBean(beanName); } /** * Increase this descriptor's nesting level. */ public void increaseNestingLevel() { this.nestingLevel++; this.resolvableType = null; if (this.methodParameter != null) { this.methodParameter = this.methodParameter.nested(); } } /** * Optionally set the concrete class that contains this dependency. * This may differ from the class that declares the parameter/field in that * it may be a subclass thereof, potentially substituting type variables. * @since 4.0 */ public void setContainingClass(Class<?> containingClass) { this.containingClass = containingClass; this.resolvableType = null; if (this.methodParameter != null) { this.methodParameter = this.methodParameter.withContainingClass(containingClass); } } /** * Build a {@link ResolvableType} object for the wrapped parameter/field. * @since 4.0 */ public ResolvableType getResolvableType() { ResolvableType resolvableType = this.resolvableType; if (resolvableType == null) { resolvableType = (this.field != null ? ResolvableType.forField(this.field, this.nestingLevel, this.containingClass) : ResolvableType.forMethodParameter(obtainMethodParameter())); this.resolvableType = resolvableType; } return resolvableType; } /** * Build a {@link TypeDescriptor} object for the wrapped parameter/field. * @since 5.1.4 */ public TypeDescriptor getTypeDescriptor() { TypeDescriptor typeDescriptor = this.typeDescriptor; if (typeDescriptor == null) { typeDescriptor = (this.field != null ? new TypeDescriptor(getResolvableType(), getDependencyType(), getAnnotations()) : new TypeDescriptor(obtainMethodParameter())); this.typeDescriptor = typeDescriptor; } return typeDescriptor; } /** * Return whether a fallback match is allowed. * <p>This is {@code false} by default but may be overridden to return {@code true} in order * to suggest to an {@link org.springframework.beans.factory.support.AutowireCandidateResolver} * that a fallback match is acceptable as well. * @since 4.0 */ public boolean fallbackMatchAllowed() { return false; } /** * Return a variant of this descriptor that is intended for a fallback match. * @since 4.0 * @see #fallbackMatchAllowed() */ public DependencyDescriptor forFallbackMatch() { return new DependencyDescriptor(this) { @Override public boolean fallbackMatchAllowed() { return true; } }; } /** * Initialize parameter name discovery for the underlying method parameter, if any. * <p>This method does not actually try to retrieve the parameter name at * this point; it just allows discovery to happen when the application calls * {@link #getDependencyName()} (if ever). */ public void initParameterNameDiscovery(@Nullable ParameterNameDiscoverer parameterNameDiscoverer) { if (this.methodParameter != null) { this.methodParameter.initParameterNameDiscovery(parameterNameDiscoverer); } } /** * Determine the name of the wrapped parameter/field. * @return the declared name (never {@code null}) */ @Nullable public String getDependencyName() { return (this.field != null ? this.field.getName() : obtainMethodParameter().getParameterName()); } /** * Determine the declared (non-generic) type of the wrapped parameter/field. * @return the declared type (never {@code null}) */ public Class<?> getDependencyType() { if (this.field != null) { if (this.nestingLevel > 1) { Type type = this.field.getGenericType(); for (int i = 2; i <= this.nestingLevel; i++) { if (type instanceof ParameterizedType) { Type[] args = ((ParameterizedType) type).getActualTypeArguments(); type = args[args.length - 1]; } } if (type instanceof Class) { return (Class<?>) type; } else if (type instanceof ParameterizedType) { Type arg = ((ParameterizedType) type).getRawType(); if (arg instanceof Class) { return (Class<?>) arg; } } return Object.class; } else { return this.field.getType(); } } else { return obtainMethodParameter().getNestedParameterType(); } } @Override public boolean equals(@Nullable Object other) { if (this == other) { return true; } if (!super.equals(other)) { return false; } DependencyDescriptor otherDesc = (DependencyDescriptor) other; return (this.required == otherDesc.required && this.eager == otherDesc.eager && this.nestingLevel == otherDesc.nestingLevel && this.containingClass == otherDesc.containingClass); } @Override public int hashCode() { return (31 * super.hashCode() + ObjectUtils.nullSafeHashCode(this.containingClass)); } //--------------------------------------------------------------------- // Serialization support //--------------------------------------------------------------------- private void readObject(ObjectInputStream ois) throws IOException, ClassNotFoundException { // Rely on default serialization; just initialize state after deserialization. ois.defaultReadObject(); // Restore reflective handles (which are unfortunately not serializable) try { if (this.fieldName != null) { this.field = this.declaringClass.getDeclaredField(this.fieldName); } else { if (this.methodName != null) { this.methodParameter = new MethodParameter( this.declaringClass.getDeclaredMethod(this.methodName, this.parameterTypes), this.parameterIndex); } else { this.methodParameter = new MethodParameter( this.declaringClass.getDeclaredConstructor(this.parameterTypes), this.parameterIndex); } for (int i = 1; i < this.nestingLevel; i++) { this.methodParameter = this.methodParameter.nested(); } } } catch (Throwable ex) { throw new IllegalStateException("Could not find original class structure", ex); } } /** * Inner class to avoid a hard dependency on Kotlin at runtime. */ private static class KotlinDelegate { /** * Check whether the specified {@link Field} represents a nullable Kotlin type or not. */ public static boolean isNullable(Field field) { KProperty<?> property = ReflectJvmMapping.getKotlinProperty(field); return (property != null && property.getReturnType().isMarkedNullable()); } } }