Merge pull request #260 from mercyblitz/dev-1.x

Refine documentation and simplify ListenableAutowireCandidateResolver

Author: mercyblitz

README.md

@@ -91,8 +91,8 @@ Choose the version that matches your Spring Framework line:
 
 | Branch | Spring Framework compatibility | Latest version |
 |--------|--------------------------------|----------------|
-| `main` | 6.0.x – 7.0.x                  | `0.2.29`       |
-| `1.x`  | 4.3.x – 5.3.x                  | `0.1.29`       |
+| `main` | 6.0.x – 7.0.x                  | `0.2.30`       |
+| `1.x`  | 4.3.x – 5.3.x                  | `0.1.30`       |
 
 ### 2. Add individual modules
 

microsphere-spring-context/src/main/java/io/microsphere/spring/beans/factory/support/ListenableAutowireCandidateResolver.java

@@ -16,9 +16,7 @@
  */
 package io.microsphere.spring.beans.factory.support;
 
-import io.microsphere.annotation.ConfigurationProperty;
 import io.microsphere.annotation.Nullable;
-import io.microsphere.constants.PropertyConstants;
 import io.microsphere.logging.Logger;
 import org.springframework.beans.BeansException;
 import org.springframework.beans.factory.BeanFactory;
@@ -28,27 +26,18 @@
 import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
 import org.springframework.beans.factory.config.DependencyDescriptor;
 import org.springframework.beans.factory.support.AutowireCandidateResolver;
-import org.springframework.beans.factory.support.BeanDefinitionRegistry;
 import org.springframework.beans.factory.support.DefaultListableBeanFactory;
-import org.springframework.context.ConfigurableApplicationContext;
-import org.springframework.context.EnvironmentAware;
-import org.springframework.core.env.Environment;
 
 import java.lang.invoke.MethodHandle;
 import java.util.List;
 
-import static io.microsphere.annotation.ConfigurationProperty.APPLICATION_SOURCE;
 import static io.microsphere.collection.Lists.ofList;
 import static io.microsphere.invoke.MethodHandleUtils.findVirtual;
 import static io.microsphere.invoke.MethodHandleUtils.handleInvokeExactFailure;
 import static io.microsphere.logging.LoggerFactory.getLogger;
-import static io.microsphere.spring.beans.factory.BeanFactoryUtils.asBeanDefinitionRegistry;
 import static io.microsphere.spring.beans.factory.BeanFactoryUtils.asDefaultListableBeanFactory;
 import static io.microsphere.spring.beans.factory.support.AutowireCandidateResolvingListener.loadListeners;
-import static io.microsphere.spring.beans.factory.support.BeanRegistrar.registerInfrastructureBean;
-import static io.microsphere.spring.constants.PropertyConstants.MICROSPHERE_SPRING_PROPERTY_NAME_PREFIX;
 import static io.microsphere.util.ArrayUtils.combine;
-import static java.lang.Boolean.parseBoolean;
 import static org.springframework.beans.BeanUtils.instantiateClass;
 
 /**
@@ -62,22 +51,10 @@
  * <h3>Key Features</h3>
  * <ul>
  *     <li>Wraps the existing {@link AutowireCandidateResolver} in a Spring bean factory</li>
- *     <li>Supports dynamic registration of resolving listeners</li>
+ *     <li>Supports dynamic registration of resolving listeners based on Spring Beans or Spring Factories</li>
  *     <li>Provides lifecycle integration through {@link BeanFactoryPostProcessor}</li>
- *     <li>Configurable via environment properties (e.g., enable/disable)</li>
  * </ul>
  *
- * <h3>Example Usage</h3>
- * <pre>{@code
- * // Register as infrastructure bean
- * ListenableAutowireCandidateResolver.register(applicationContext);
- *
- * // Add custom listener
- * ListenableAutowireCandidateResolver resolver = beanFactory.getBean(ListenableAutowireCandidateResolver.class);
- * resolver.addListener((descriptor, candidates) -> {
- *     System.out.println("Resolved candidates for " + descriptor.getDependencyType());
- * });
- * }</pre>
  *
  * <h3>Configuration</h3>
  * Enable the resolver using property configuration:
@@ -90,10 +67,11 @@
  * @see AutowireCandidateResolvingListener
  * @see CompositeAutowireCandidateResolvingListener
  * @see DefaultListableBeanFactory#setAutowireCandidateResolver(AutowireCandidateResolver)
+ * @see BeanFactoryPostProcessor
  * @since 1.0.0
  */
 public class ListenableAutowireCandidateResolver implements AutowireCandidateResolver, BeanFactoryPostProcessor,
-        EnvironmentAware, BeanNameAware {
+        BeanNameAware {
 
     private static final Logger logger = getLogger(ListenableAutowireCandidateResolver.class);
 
@@ -118,35 +96,10 @@ public class ListenableAutowireCandidateResolver implements AutowireCandidateRes
      */
     private static final MethodHandle CLONE_IF_NECESSARY_METHOD_HANDLE = findVirtual(AutowireCandidateResolver.class, "cloneIfNecessary");
 
-    /**
-     * The prefix of the property name of {@link ListenableAutowireCandidateResolver}
-     */
-    public static final String PROPERTY_NAME_PREFIX = MICROSPHERE_SPRING_PROPERTY_NAME_PREFIX + "listenable-autowire-candidate-resolver.";
-
-    private static final String DEFAULT_ENABLED = "false";
-
-    /**
-     * The property name of {@link ListenableAutowireCandidateResolver} to be 'enabled'
-     */
-    @ConfigurationProperty(
-            type = boolean.class,
-            defaultValue = DEFAULT_ENABLED,
-            description = "The property name of ListenableAutowireCandidateResolver to be enabled or not",
-            source = APPLICATION_SOURCE
-    )
-    public static final String ENABLED_PROPERTY_NAME = PROPERTY_NAME_PREFIX + PropertyConstants.ENABLED_PROPERTY_NAME;
-
-    /**
-     * The default property value of {@link ListenableAutowireCandidateResolver} to be 'enabled'
-     */
-    public static final boolean DEFAULT_ENABLED_PROPERTY_VALUE = parseBoolean(DEFAULT_ENABLED);
-
     private AutowireCandidateResolver delegate;
 
     private CompositeAutowireCandidateResolvingListener compositeListener;
 
-    private Environment environment;
-
     private String beanName;
 
     /**
@@ -366,38 +319,6 @@ public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory)
         wrap(beanFactory);
     }
 
-    /**
-     * {@inheritDoc}
-     * <p>Stores the {@link Environment} for later use in determining whether this resolver is
-     * {@link #isEnabled(Environment) enabled} and for resolving configuration properties.
-     *
-     * <h3>Example Usage</h3>
-     * <pre>{@code
-     *   // Typically called automatically by Spring's EnvironmentAware callback.
-     *   // The environment can be configured with the enabling property:
-     *   //   microsphere.spring.listenable-autowire-candidate-resolver.enabled=true
-     * }</pre>
-     *
-     * @param environment the {@link Environment} to set
-     */
-    @Override
-    public void setEnvironment(Environment environment) {
-        this.environment = environment;
-    }
-
-    /**
-     * {@inheritDoc}
-     * <p>Stores the bean name assigned to this resolver instance for logging and diagnostics.
-     *
-     * <h3>Example Usage</h3>
-     * <pre>{@code
-     *   // Typically called automatically by Spring's BeanNameAware callback.
-     *   // The bean is registered as an infrastructure bean:
-     *   ListenableAutowireCandidateResolver.register(applicationContext);
-     * }</pre>
-     *
-     * @param name the name of this bean in the Spring container
-     */
     @Override
     public void setBeanName(String name) {
         this.beanName = name;
@@ -410,16 +331,6 @@ public void setBeanName(String name) {
      * @param beanFactory {@link DefaultListableBeanFactory}
      */
     public void wrap(BeanFactory beanFactory) {
-        if (!isEnabled(this.environment)) {
-            if (logger.isInfoEnabled()) {
-                logger.info("The ListenableAutowireCandidateResolver bean[name : '{}'] is disabled.", this.beanName);
-                logger.info("Setting the configuration property '{} = true' to enable it if requires.", ENABLED_PROPERTY_NAME);
-            }
-            return;
-        }
-        if (logger.isTraceEnabled()) {
-            logger.trace("The ListenableAutowireCandidateResolver bean[name : '{}'] is enabled.", this.beanName);
-        }
         DefaultListableBeanFactory dbf = asDefaultListableBeanFactory(beanFactory);
         AutowireCandidateResolver autowireCandidateResolver = dbf.getAutowireCandidateResolver();
         if (autowireCandidateResolver != this) {
@@ -428,28 +339,7 @@ public void wrap(BeanFactory beanFactory) {
             this.delegate = autowireCandidateResolver;
             this.compositeListener = compositeListener;
             dbf.setAutowireCandidateResolver(this);
+            logger.info("The ListenableAutowireCandidateResolver has been wrapped and registered to BeanFactory[{}]", dbf);
         }
     }
-
-    /**
-     * Determine whether the {@link ListenableAutowireCandidateResolver} is enabled or not
-     *
-     * @param environment {@link Environment}
-     * @return <code>true</code> if enabled, otherwise <code>false</code>
-     */
-    public static boolean isEnabled(Environment environment) {
-        return environment.getProperty(ENABLED_PROPERTY_NAME, boolean.class, DEFAULT_ENABLED_PROPERTY_VALUE);
-    }
-
-    /**
-     * Register the {@link ListenableAutowireCandidateResolver} as the infrastructure bean
-     *
-     * @param applicationContext {@link ConfigurableApplicationContext}
-     */
-    public static void register(ConfigurableApplicationContext applicationContext) {
-        ConfigurableListableBeanFactory beanFactory = applicationContext.getBeanFactory();
-        BeanDefinitionRegistry beanDefinitionRegistry = asBeanDefinitionRegistry(beanFactory);
-        registerInfrastructureBean(beanDefinitionRegistry, ListenableAutowireCandidateResolver.class);
-    }
-
 }

microsphere-spring-context/src/main/java/io/microsphere/spring/beans/factory/support/ListenableAutowireCandidateResolverInitializer.java

@@ -20,32 +20,56 @@
 import io.microsphere.constants.PropertyConstants;
 import io.microsphere.spring.context.ConfigurableApplicationContextInitializer;
 import io.microsphere.spring.core.env.ListenableConfigurableEnvironment;
+import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
 import org.springframework.context.ApplicationContextInitializer;
 import org.springframework.context.ConfigurableApplicationContext;
 import org.springframework.core.env.ConfigurableEnvironment;
 
-import static io.microsphere.spring.beans.factory.support.ListenableAutowireCandidateResolver.register;
+import static io.microsphere.spring.beans.factory.BeanFactoryUtils.asBeanDefinitionRegistry;
+import static io.microsphere.spring.beans.factory.support.BeanRegistrar.registerBeanDefinition;
 import static io.microsphere.spring.constants.PropertyConstants.MICROSPHERE_SPRING_PROPERTY_NAME_PREFIX;
 import static java.lang.Boolean.parseBoolean;
 
 /**
  * An {@link ApplicationContextInitializer} implementation that registers a
  * {@link ListenableAutowireCandidateResolver} to provide extensible autowiring
  * capabilities within the Spring application context.
+ * <p>
+ * It allows developers to customize the autowire candidate resolution strategy
+ * based on specific requirements, such as conditional bean matching or external configuration.
+ * The functionality is disabled by default and can be enabled via configuration properties.
+ *
+ * <h3>Configuration Properties</h3>
+ * <ul>
+ *     <li>{@code microsphere.spring.listenable-autowire-candidate-resolver.enabled} -
+ *         Whether to enable the {@link ListenableAutowireCandidateResolver} (default: {@code false}).</li>
+ * </ul>
  *
  * <h3>Example Usage</h3>
+ * <h4>1. Configuration</h4>
+ * <p><strong> application.properties (Spring Boot):</strong></p>
+ * <pre>
+ * microsphere.spring.listenable-autowire-candidate-resolver.enabled=true
+ * </pre>
+ *
+ * <p><strong> spring.factories (Spring Boot):</strong></p>
  * <pre>{@code
- * public class MyConfig implements WebMvcConfigurer {
- *     // Configuration code...
- * }
+ * org.springframework.context.ApplicationContextInitializer=\
+ * io.microsphere.spring.beans.factory.support.ListenableAutowireCandidateResolverInitializer
  * }</pre>
  *
- * <p>This initializer should be registered with a {@link org.springframework.context.ApplicationContext}
- * to enable custom autowiring logic during the application context initialization phase.
+ * <h4>2. Programmatic</h4>
+ * <pre>{@code
+ * new SpringApplicationBuilder(MyApplication.class)
+ *  .initializers(new ListenableAutowireCandidateResolverInitializer())
+ *  .properties("microsphere.spring.listenable-autowire-candidate-resolver.enabled=true")
+ *  .run(args);
+ * }</pre>
  *
- * @author <a href="mailto:mercyblitz@gmail.com">Mercy<a/>
+ * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see ListenableAutowireCandidateResolver
- * @see ApplicationContextInitializer
+ * @see ConfigurableApplicationContextInitializer
  * @since 1.0.0
  */
 public class ListenableAutowireCandidateResolverInitializer extends ConfigurableApplicationContextInitializer {
@@ -74,7 +98,9 @@ public class ListenableAutowireCandidateResolverInitializer extends Configurable
 
     @Override
     protected void initialize(ConfigurableApplicationContext context, ConfigurableEnvironment environment) {
-        register(context);
+        ConfigurableListableBeanFactory beanFactory = context.getBeanFactory();
+        BeanDefinitionRegistry beanDefinitionRegistry = asBeanDefinitionRegistry(beanFactory);
+        registerBeanDefinition(beanDefinitionRegistry, ListenableAutowireCandidateResolver.class);
     }
 
     @Override

microsphere-spring-context/src/main/java/io/microsphere/spring/context/event/EventPublishingBeanInitializer.java

@@ -29,7 +29,39 @@
 import static java.lang.Boolean.parseBoolean;
 
 /**
- * {@link ApplicationContextInitializer} for Publishing Bean Event with the highest priority
+ * An {@link ApplicationContextInitializer} that registers processors to publish Spring bean lifecycle events
+ * during context initialization.
+ * <p>
+ * This initializer executes with the highest priority to guarantee that bean event publishing capabilities
+ * are established before other components are processed. It automatically registers an
+ * {@link EventPublishingBeanBeforeProcessor} as a {@link org.springframework.beans.factory.config.BeanFactoryPostProcessor}.
+ *
+ * <h3>Configuration Properties</h3>
+ * <ul>
+ *     <li>{@code microsphere.spring.event-publishing-bean.enabled} -
+ *         Whether to enable the EventPublishingBean* (default: {@code false}).</li>
+ * </ul>
+ *
+ * <h3>Example Usage</h3>
+ * <h4>1. Configuration</h4>
+ * <p><strong> application.properties (Spring Boot):</strong></p>
+ * <pre>
+ * microsphere.spring.event-publishing-bean.enabled=true
+ * </pre>
+ *
+ * <p><strong> spring.factories (Spring Boot):</strong></p>
+ * <pre>{@code
+ * org.springframework.context.ApplicationContextInitializer=\
+ * io.microsphere.spring.context.event.EventPublishingBeanInitializer
+ * }</pre>
+ *
+ * <h4>2. Programmatic</h4>
+ * <pre>{@code
+ * new SpringApplicationBuilder(MyApplication.class)
+ *  .initializers(new EventPublishingBeanInitializer())
+ *  .properties("microsphere.spring.event-publishing-bean.enabled=true")
+ *  .run(args);
+ * }</pre>
  *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see EventPublishingBeanBeforeProcessor

microsphere-spring-context/src/main/java/io/microsphere/spring/core/env/ListenableConfigurableEnvironmentInitializer.java

@@ -27,9 +27,37 @@
 import static java.lang.Boolean.parseBoolean;
 
 /**
- * The Initializer of {@link ListenableConfigurableEnvironment} based on {@link ApplicationContextInitializer}
+ * An {@link ApplicationContextInitializer} implementation that initializes {@link ConfigurableEnvironment}
+ * with {@link ListenableConfigurableEnvironment} to enable listening for environment changes.
  *
- * @author <a href="mailto:mercyblitz@gmail.com">Mercy<a/>
+ * <h3>Configuration Properties</h3>
+ * <ul>
+ *     <li>{@code microsphere.spring.listenable-environment.enabled} -
+ *         Whether to enable the {@link ListenableConfigurableEnvironment} (default: {@code false}).</li>
+ * </ul>
+ *
+ * <h3>Example Usage</h3>
+ * <h4>1. Configuration</h4>
+ * <p><strong> application.properties (Spring Boot):</strong></p>
+ * <pre>
+ * microsphere.spring.listenable-environment.enabled=true
+ * </pre>
+ *
+ * <p><strong> spring.factories (Spring Boot):</strong></p>
+ * <pre>{@code
+ * org.springframework.context.ApplicationContextInitializer=\
+ * io.microsphere.spring.beans.factory.support.ListenableConfigurableEnvironmentInitializer
+ * }</pre>
+ *
+ * <h4>2. Programmatic</h4>
+ * <pre>{@code
+ * new SpringApplicationBuilder(MyApplication.class)
+ *  .initializers(new ListenableConfigurableEnvironmentInitializer())
+ *  .properties("microsphere.spring.listenable-environment.enabled=true")
+ *  .run(args);
+ * }</pre>
+ *
+ * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see ListenableConfigurableEnvironment
  * @see EnvironmentListener
  * @see ProfileListener

microsphere-spring-context/src/test/java/io/microsphere/spring/beans/factory/support/ListenableAutowireCandidateResolverTest.java

@@ -26,7 +26,7 @@
 
 import static io.microsphere.logging.test.junit4.LoggingLevelsRule.levels;
 import static io.microsphere.reflect.FieldUtils.findField;
-import static io.microsphere.spring.beans.factory.support.ListenableAutowireCandidateResolver.ENABLED_PROPERTY_NAME;
+import static io.microsphere.spring.beans.factory.support.ListenableAutowireCandidateResolverInitializer.ENABLED_PROPERTY_NAME;
 import static io.microsphere.spring.core.SpringVersion.CURRENT;
 import static io.microsphere.spring.core.SpringVersion.SPRING_5_1;
 import static org.junit.Assert.assertEquals;